Skip to main content

将 Webhook 与 GitHub 应用配合使用

GitHub App可以订阅 Webhook 事件,在发生特定活动时接收通知。

关于 Webhook 和 GitHub Apps

使用 Webhook,在 GitHub 上发生事件(例如当有人在应用可以访问的存储库中推送提交或提交拉取请求)时,你的 GitHub App可以接收实时通知。 有关 Webhook 的详细信息,请参阅“关于 web 挂钩”。 有关演示如何将 Webhook 与 GitHub App 配合使用的教程,请参阅“构建响应 Webhook 事件的 GitHub 应用”。

可以将 GitHub App配置为接收 GitHub 上特定事件的 Webhook,并自动对其执行操作。 有关可以接收的 Webhook 类型的详细信息,请参阅“Webhook 事件和有效负载”。

若要在 GitHub App中接收 Webhook 事件,必须为 GitHub App 注册启用 Webhook,并指定一个 Webhook URL,其中 GitHub 将发送 Webhook 有效负载。

如果 GitHub App 不需要响应 Webhook 或仅用于身份验证,则可以关闭用于 GitHub App 注册的 Webhook 功能。 无需指定 Webhook URL。

若要详细了解如何注册 GitHub App,请参阅“注册 GitHub 应用”。 有关更改 GitHub App 注册订阅的 Webhook 的详细信息,请参阅“修改 GitHub 应用注册”。

选择 Webhook URL

为 GitHub App注册激活 Webhook 时,需要指定 Webhook URL。 Webhook URL 是 Web 服务器的地址,将接收发送到 GitHub App的 Webhook 事件有效负载。 然后,服务器可以根据有效负载的内容执行操作。 应选择适合 GitHub App将遇到的 Webhook 流量的 Web 服务器。

选择用于开发和测试的 Webhook URL

在开发和测试应用时,可以使用 Smee 等 Webhook 有效负载传递服务捕获 Webhook 有效负载并将其转发到本地开发环境。 切勿对生产中的应用程序使用 Smee,因为 Smee 通道未经身份验证或安全性不明。 或者,可以使用 ngroklocaltunnelHookdeck 控制台等工具,向 Internet 公开本地计算机以接收有效负载。

使用 Smee 创建 Webhook URL

可以使用 Smee 创建唯一的域,其中 GitHub 可以发送 Webhook 有效负载,而无需向 Internet 公开本地开发。 Smee 将这个唯一的域称为“Webhook 代理 URL”。 可以使用 Smee 的 Webhook 代理 URL 作为 GitHub App的 Webhook URL。

  1. 若要使用 Smee 创建唯一的域,请转到 https://smee.io ,然后单击“启动新通道”。
  2. 在 Smee 通道页上,按照“使用 CLI”下的说明安装和运行 Smee 客户端。
  3. 若要将 Smee Webhook URL 连接到 GitHub App,请在 GitHub App 注册页上的“Webhook URL”字段中输入唯一的 Smee 域。 有关详细信息,请参阅“注册 GitHub 应用”和“修改 GitHub 应用注册”。

选择用于生产的 Webhook URL

对于在生产环境中接收低流量 Webhook 的应用程序,可以将它托管在任何动态应用程序服务器上。 用于处理 Webhook 的服务器端代码可以接收事件、反序列化其 JSON 有效负载,并确定要执行的操作,例如将数据存储在数据库中或调用 GitHub API。

若要为生产环境中的大型应用处理高流量的 Webhook,请考虑在专用服务器上使用异步 Webhook 处理。 可以通过使用队列来实现此目的,其中 Webhook 处理程序将数据推送到队列,单独的进程会根据事件执行后续操作。 此外,还可以使用 Azure FunctionsAWS LambdaHookdeck 等云函数来帮助缩放应用,以处理大量 Webhook 事件。

使用 Webhook 机密保护 Webhook

将服务器配置为接收有效负载后,它将侦听发送到服务器的任何有效负载。 出于安全考虑,应将传入请求限制为仅源自 GitHub 的请求。 为此,可以为应用创建 Webhook 机密。

若要为 GitHub 应用创建 Webhook 机密,请在 GitHub App 注册页上的“Webhook 机密”下键入机密令牌。 应选择高熵的随机文本字符串。 有关详细信息,请参阅“注册 GitHub 应用”和“修改 GitHub 应用注册”。

为应用创建 Webhook 机密后,需要配置服务器以安全地存储和验证 Webhook 机密令牌。 有关详细信息,请参阅“验证 Webhook 交付”。

订阅 Webhook 事件

可以订阅 GitHub App以接收特定事件的 Webhook 有效负载。 可以为 GitHub App 注册选择的具体 Webhook 事件根据为应用选择的权限类型而定。 首先需要选择希望应用拥有的权限,然后可以让应用订阅与该权限集相关的 Webhook 事件。 有关详细信息,请参阅“为 GitHub Apps 选择权限”。

例如,如果希望每当存储库中提交了新问题时,应用都能接收 Webhook 事件有效负载,你首先需要在“存储库权限”下授予应用相关权限,应用才能访问“问题”。 然后在“订阅事件”下,可以选择“问题”。

有关每个 Webhook 事件所需权限的详细信息,请参阅“Webhook 事件和有效负载”。