创建 web 挂钩

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

我们已了解 web 挂钩的基础知识,现在我们来构建自己的 web 挂钩支持的集成。 在本教程中,我们将创建一个仓库 web 挂钩,它将负责根据仓库每天收到的议题数量列出仓库的受欢迎程度。

创建 web 挂钩是一个两步过程。 首先需要设置 web 挂钩通过 GitHub 实施的行为 - 它应该侦听哪些事件。 之后,您将设置服务器以接收和管理有效负载。

您可以使用仓库、组织和应用 web 挂钩 REST API 来创建、更新、删除和 ping web 挂钩。 您也可以使用 REST API 来更改 web 挂钩的配置。 例如,您可以修改有效负载 URL、内容类型、SSL 验证和机密。 更多信息请参阅:

向互联网显示本地主机

在本教程中,我们将使用本地服务器接收来自 GitHub 的消息。 因此,首先,我们需要将我们的本地发展环境显示给互联网。 我们将使用 ngrok 实现此目的。 所有主要操作系统均可免费使用 ngrok。 更多信息请参阅 ngrok 下载页面

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

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

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

设置 web 挂钩

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

要设置 web 挂钩,请转到仓库或组织的设置页面。 在那里,单击 Webhooks(web 挂钩),然后单击 Add webhook(添加 web 挂钩)

或者,您可以选择通过 web 挂钩 API 来构建和管理 web 挂钩。

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

有效负载 URL

有效负载 URL 是接收 web 挂钩 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

密钥

设置 web 挂钩密钥使您可以确保将 POST 请求发送到来自 GitHub 的有效负载 URL。 在设置机密时,您将在 web 挂钩 POST 请求中收到 X-Hub-SignatureX-Hub-Signature-256 标头。 有关如何使用密钥和签名标头来保护 web 挂钩有效负载的更多信息,请参阅“保护 web 挂钩”。

SSL 验证

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

已激活

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

事件

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

有关 web 挂钩事件的完整列表以及它们在什么情况下执行,请参阅 web 挂钩 API 参考资料。

由于我们的 web 挂钩与仓库中的议题相关,因此我们单击 Let me select individual events(让我选择单个事件),然后单击 Issues(议题)。 确保选择 Active(激活)以接收触发 web 挂钩的议题事件。 您还可以使用默认选项选择所有事件。

完成后,单击 Add webhook(添加 web 挂钩)

现在您创建了 web 挂钩,是时候设置我们的本地服务器来测试 web 挂钩了。 请参阅配置服务器了解如何进行测试。

通配符事件

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

此文档对您有帮助吗?隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。