Skip to main content

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

创建 web 挂钩

了解如何构建 web 挂钩,选择 web 挂钩将在 GitHub 上侦听的事件,以及如何设置服务器以接收和管理 web 挂钩负载。

学完 webhook 的基础知识后,接下来了解如何生成自己的基于 webhook 的集成。 在本教程中,我们将创建一个仓库 web 挂钩,它将负责根据仓库每天收到的议题数量列出仓库的受欢迎程度。

创建 web 挂钩是一个两步过程。 首先需要设置 Webhook 应侦听的事件。 之后,您将设置服务器以接收和管理有效负载。

使用 Webhook REST API,可以管理存储库、组织和应用 Webhook。 可使用此 API 列出 Webhook 的 Webhook 交付,获取并重新交付 Webhook 的个别交付,该交付可以集成到外部应用或服务中。 还可使用 REST API 更改 Webhook 的配置。 例如,您可以修改有效负载 URL、内容类型、SSL 验证和机密。 有关详细信息,请参阅:

向互联网显示本地主机

在本教程中,我们将使用本地服务器接收来自 GitHub 的 Webhook 事件。

首先,我们需要向 Internet 公开本地开发环境,以便 GitHub 可以传递事件。 我们将使用 ngrok 实现此目的。

所有主要操作系统均可免费使用 ngrok。 有关详细信息,请参阅 ngrok 下载页面

安装 ngrok 后,可以通过在命令行上运行 ./ngrok http 4567 来公开本地主机。 4567 是我们服务器侦听消息的端口号。 您应该会看到如下所示的行:

$ Forwarding  http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567

记下 *.ngrok.io URL。 我们将用它来设置 web 挂钩。

设置 Webhook

您可以在组织或特定仓库上安装 web 挂钩。

要设置 web 挂钩,请转到仓库或组织的设置页面。 然后,依次单击“Webhook”和“添加 Webhook” 。

另外,你可以选择使用 Webhook API 生成和管理 Webhook。

Web 挂钩需要设置几个配置选项才能使用。 我们将在下面介绍所有这些设置。

有效负载 URL

有效负载 URL 是将接收 Webhook POST 请求的服务器的 URL。

由于我们为本教程进行本地开发,因此将其设置为 *.ngrok.io URL,且后接 /payload。 例如 http://7e9ea9dc.ngrok.io/payload

内容类型

Web 挂钩可通过不同的内容类型传递:

  • application/json 内容类型直接将 JSON 有效负载作为 POST 请求的正文传递。
  • application/x-www-form-urlencoded 内容类型将 JSON 有效负载作为表单参数发送,称为 payload

选择最符合你需要的预设。 对于本教程,默认的内容类型 application/json 适用。

机密

通过设置 Webhook 机密,可以确保发送到有效负载 URL 的 POST 请求来自 GitHub Enterprise Server。 设置机密时,你将在 Webhook POST 请求中收到 X-Hub-SignatureX-Hub-Signature-256 标头。 有关如何使用带有签名标头的机密来保护 Webhook 有效负载的详细信息,请参阅“保护 Webhook”。

SSL 验证

如果您的“有效负载 URL”是一个安全站点 (HTTPS),您可以选择配置 SSL 验证设置。 如果您的“有效负载 URL”不安全 (HTTP),GitHub 不会显示此选项。 默认情况下,GitHub 在传递 web 挂钩有效负载时验证网站的 SSL 证书。 SSL 验证有助于确保将挂钩有效负载安全地传递到 URL 端点。 你可以选择禁用 SSL,但我们建议保留“启用 SSL 验证”的选中状态。

活动

默认情况下,web 挂钩交付为“Active(激活)”。 您可以通过取消选择“Active(激活)”来选择禁用 web 挂钩交付。

事件

事件是 web 挂钩的核心。 当仓库上发生特定操作时,就会触发这些 web 挂钩,而服务器的有效负载 URL 会截获它们并采取行动。

可在 webhook API 参考中找到完整的 webhook 事件列表及其执行时间。

由于 webhook 正在处理存储库中的问题,因此单击“选择单个事件”,然后单击“问题” 。 请确保选择“可用”以接收触发的 Webhook 的问题事件。 您还可以使用默认选项选择所有事件。

完成后,单击“添加 Webhook”。

现在您创建了 web 挂钩,是时候设置我们的本地服务器来测试 web 挂钩了。 转到配置服务器,了解如何实现这一目标。

通配符事件

要为所有事件配置 webhook,请使用通配符 (*) 指定 webhook 事件。 添加通配符事件时,我们将用通配符事件替换您配置的任何现有事件,并向您发送所有受支持事件的有效负载。 您还会自动获取我们可能在将来添加的任何新事件。