Now that we understand the basics of webhooks, let's go through the process of building out our own webhook powered integration. In this tutorial, we'll create a repository webhook that will be responsible for listing out how popular our repository is, based on the number of Issues it receives per day.
Creating a webhook is a two-step process. You'll first need to set up how you want your webhook to behave through GitHub Enterprise Server--what events should it listen to. After that, you'll set up your server to receive and manage the payload.
您可以使用仓库、组织和应用 web 挂钩 REST API 来创建、更新、删除和 ping web 挂钩。 更多信息请参阅:
Setting up a Webhook
You can install webhooks on an organization or on a specific repository.
To set up a webhook, go to the settings page of your repository or organization. From there, click Webhooks, then Add webhook.
Alternatively, you can choose to build and manage a webhook through the Webhooks API.
Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.
Payload URL
有效负载 URL 是接收 web 挂钩 POST
请求的服务器的 URL。
Since we're developing locally for our tutorial, let's set it to http://localhost:4567/payload
. We'll explain why in the Configuring Your Server docs.
Content Type
Web 挂钩可通过不同的内容类型传递:
application/json
内容类型将直接传递 JSON 有效负载,作为POST
请求的正文。application/x-www-form-urlencoded
内容类型将发送 JSON 有效负载,作为名为payload
的表单参数。
选择最适合您需求的项。 For this tutorial, the default content type of application/json
is fine.
Secret
设置 web 挂钩密钥使您可以确保将 POST
请求发送到来自 GitHub Enterprise Server 的有效负载 URL。 When you set a secret, you'll receive the X-Hub-Signature
header in the webhook POST
request. 有关如何使用密钥和签名标头来保护 web 挂钩有效负载的更多信息,请参阅“保护 web 挂钩”。
SSL Verification
如果您的“有效负载 URL”是一个安全站点 (HTTPS),您可以选择配置 SSL 验证设置。 如果您的“有效负载 URL”不安全 (HTTP),GitHub 不会显示此选项。 默认情况下,GitHub 在传递 web 挂钩有效负载时验证网站的 SSL 证书。 SSL 验证有助于确保将挂钩有效负载安全地传递到 URL 端点。 您可以选择禁用 SSL,但我们建议保留Enable SSL verification(启用 SSL 验证)的选中状态。
已激活
By default, webhook deliveries are "Active." You can choose to disable the delivery of webhook payloads by deselecting "Active."
事件
Events are at the core of webhooks. These webhooks fire whenever a certain action is taken on the repository, which your server's payload URL intercepts and acts upon.
A full list of webhook events, and when they execute, can be found in the webhooks API reference.
Since our webhook is dealing with Issues in a repository, we'll click Let me select individual events and then Issues. Make sure you select Active to receive issue events for triggered webhooks. You can also select all events using the default option.
When you're finished, click Add webhook. 唷! Now that you created the webhook, it's time to set up our local server to test the webhook. Head on over to Configuring Your Server to learn how to do that.
Wildcard Event
To configure a webhook for all events, use the wildcard (*
) character to specify the webhook events. When you add the wildcard event, we'll replace any existing events you have configured with the wildcard event and send you payloads for all supported events. You'll also automatically get any new events we might add in the future.