此版本的 GitHub Enterprise Server 已于以下日期停止服务 2023-09-12. 即使针对重大安全问题，也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能，请升级到最新版本的 GitHub Enterprise。 如需升级帮助，请联系 GitHub Enterprise 支持。

关于 web 挂钩

本文内容

Webhook 是一种通知方式，只要 GitHub 上发生特定事件，就会发送通知到外部 Web 服务器。

关于 web 挂钩

Webhook 是一种通信方法，允许用户订阅软件系统中发生的事件。 只要 GitHub 上发生特定事件，就可以触发 Webhook。 例如，可以将 Webhook 配置为在以下情况下触发：

  • 将代码推送到存储库
  • 打开拉取请求
  • 构建 GitHub Pages 网站
  • 团队新增成员

可以为 GitHub Enterprise、组织、存储库或 GitHub App 创建 Webhook。

最多可以为每个安装目标（GitHub Enterprise Server 实例、特定组织或特定存储库）上的每个事件创建最多 250 个 Webhook。

有关创建 Webhook 的详细信息，请参阅“创建 web 挂钩”。

注意：GitHub Webhook 目前不支持 IPv6，但将来会支持 IPv6。 /meta REST API 终结点返回 IPv6 范围以启用该转换。

关于 Webhook 事件

配置 Webhook 时，可以选择哪些事件将向你发送有效负载。 若要限制对服务器的 HTTP 请求数，应仅订阅计划处理的特定事件。 有关 Webhook 事件及其有效负载的完整列表，请参阅“Webhook 事件和有效负载”。

某些 Webhook 事件具有的操作是可以对 Webhook 事件表示的资源执行的操作。 如果一个 Webhook 事件有多个操作类型，则每个操作都会触发有效负载交付。 例如，当包为 updated 或 edited 包时，package Webhook 事件会触发有效负载交付。 无法订阅单个 Webhook 操作。 配置 Webhook 时，将收到与该 Webhook 相关的所有操作的有效负载。

默认情况下，安装在 GitHub Enterprise、组织或存储库上的 Webhook 仅订阅 push 事件。 默认情况下，不对任何事件订阅 GitHub Apps 上的 Webhook。 可以随时更改 Webhook 订阅的事件。

Webhook 交付简介

收到 Webhook 交付时，有效负载将包含触发交付之事件和操作的名称，以及有关事件本身的其他信息。 有关每个有效负载附带的交付标头以及示例交付的详细信息，请参阅“Webhook 事件和有效负载”。 某些信息包含在大多数或所有 Webhook 交付中，例如执行事件的用户，或者发生事件的组织或存储库。

创建 Webhook 时，需要指定要接收 Webhook 事件的 URL。 当发生 Webhook 订阅的任何事件时，GitHub 将向此 URL 发送 HTTP POST 有效负载。 然后，服务器可以处理和响应 Webhook。 有关详细信息，请参阅“处理 Webhook 交付”。

注意：有效负载上限为 25 MB。 如果事件生成了更大的有效负载，web 挂钩将不会触发。 例如，如果同时推送多个分支或标记，这种情况可能会发生在 create 事件中。 我们建议监控有效负载的大小以确保成功递送。

有关查看 Webhook 交付的信息，请参阅“查看 web 挂钩交付”。

何时使用 Webhook

Webhook 可用于各种应用场景，包括：

  • 在外部 CI 服务器上触发 CI（持续集成）管道。 例如，当代码被推送到分支时，在 Jenkins 或 CircleCI 中触发 CI。
  • 当 GitHub 上发生事件时，向协作平台发送通知。 例如，当对拉取请求进行审阅时，向 Discord 或 Slack 发送通知。
  • 更新外部问题跟踪器，例如 Jira。
  • 部署到生产服务器。
  • 记录 GitHub 上发生的事件用于审核。

Webhook 允许在发生时接收数据，而不是间歇性地调用 API 来查看数据是否可用（也称为轮询更新）。 只需在创建 Webhook 时表达一次对事件的兴趣，即可实现前述目的。

与使用 API 相比，Webhook 具有以下优势：

  • 与轮询 API 相比，Webhook 所需的工作量和资源更少。
  • Webhook 的缩放性能优于 API 调用。 如果需要监视许多资源，为每个资源调用 API 可能会导致快速达到 API 速率限制配额。 我们可以转而订阅多个 Webhook 事件，并仅在事件发生时接收信息。
  • Webhook 允许准实时的更新，因为事件发生之时就会触发 Webhook。

如果只需要一次或间歇性的信息，或者只想从少量资源获取信息，且没有纵向扩展计划，则可以在需要相关信息时调用 API。

有关使用 Webhook 时要遵循的最佳做法的信息，请参阅“使用 Webhook 的最佳做法”。

关于管理 Webhook 的权限

若要管理 Webhook，必须拥有创建 Webhook 并侦听事件的资源或具有该资源的管理员访问权限。 例如，需要组织的管理员权限才能管理组织 Webhook。 有关创建不同类型的 Webhook 的详细信息，请参阅“创建 web 挂钩”。

将传统的 GitHub 服务替换为 Webhook

GitHub 服务（有时称为服务挂钩）是传统的集成方法，其中 GitHub 通过 github-services 存储库托管集成者的部分服务。 2019 年，我们弃用了 GitHub 服务，转而支持与 Webhook 集成。 有关弃用的详细信息，请参阅博客文章。