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 の個別の配信を取得して再配信したりできます。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.
Organizationのオーナー権限もしくはリポジトリの管理者権限を持つメンバーだけが、 manage webhooks for an organization. 詳しくは、「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 はサポートされていませんが、今後サポートされる予定です。 /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
webhookは、様々なコンテンツタイプを使って配信できます。
application/jsonのコンテンツ タイプは、POST要求の本文として JSON ペイロードを直接配信します。application/x-www-form-urlencodedのコンテンツ タイプは、payloadというフォーム パラメーターとして JSON ペイロードを送信します。
ニーズに最適なプリセットを選択してください。 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はこのオプションを表示しません。 デフォルトでは、webhookのペイロードを配信する際に、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 が正しくセットアップされたことが通知されます。 このイベントは格納されないため、Events API エンドポイントを介して取得することはできません。
For more information about the ping event webhook payload, see the ping event.