Skip to main content

Creating webhooks

Learn to build a webhook, choosing the events your webhook will listen for on GitHub and how to set up a server to receive and manage the webhook payload.

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 what events your webhook should listen to. After that, you'll set up your server to receive and manage the payload.

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

Exposing localhost to the internet

For the purposes of this tutorial, we're going to use a local server to receive webhook events from GitHub.

First of all, we need to expose our local development environment to the internet so GitHub can deliver events. We'll use ngrok to do this.

Note: Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see "Receiving webhooks with the GitHub CLI."

ngrok is available, free of charge, for all major operating systems. For more information, see the ngrok download page.

After installing ngrok, you can expose your localhost by running ./ngrok http 4567 on the command line. 4567 is the port number on which our server will listen for messages. You should see a line that looks something like this:

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

Make a note of the *.ngrok.io URL. We'll use it to set up our webhook.

Setting up a webhook

You can install webhooks on an organization or on a specific repository.

只有拥有组织所有者权限或仓库管理员权限的成员才能 manage webhooks for an organization. 有关详细信息,请参阅“组织中的角色”。

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

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

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

Since we're developing locally for our tutorial, we'll set it to the *.ngrok.io URL, followed by /payload. For example, http://7e9ea9dc.ngrok.io/payload.

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

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

SSL verification

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

Active

By default, webhook deliveries are "Active." You can choose to disable the delivery of webhook payloads by deselecting "Active."

Events

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've 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.

Ping event

当你创建新的 Webhook 时,我们将向你发送一个简单的 ping 事件,让你知道你已正确设置 Webhook。 此事件不会存储,因此无法通过事件 API 终结点进行检索。

For more information about the ping event webhook payload, see the ping event.

⌂ Proxy