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.
webhookの作成は、2ステップのプロセスです。 You'll first need to set up how you want your webhook to behave through GitHub Enterprise Server: what events should it listen to. その後、ペイロードを受信して管理するようにサーバーをセットアップします。
webhookの作成、更新、削除、pingには、リポジトリ、Organization、アプリケーションのwebhook REST APIが使用できます。 詳しい情報については以下を参照してください。
Exposing localhost to the internet
For the purposes of this tutorial, we're going to use a local server to receive messages from GitHub. So, first of all, we need to expose our local development environment to the internet. We'll use ngrok to do this. 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. 以下のような行が表示されるはずです。
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567Make a note of the *.ngrok.io URL. We'll use it to set up our webhook.
Setting up a webhook
webhookは、Organizationもしくは特定のリポジトリにインストールできます。
webhookをセットアップするには、リポジトリもしくはOrganizationのsettings（設定）ページにアクセスしてください。 そこからWebhooksをクリックし、続いてAdd webhook（webhookの追加）をクリックしてください。
あるいは、Webhooks APIを通じてwebhookの構築と管理を行うこともできます。
webhookには、利用を開始する前にいくつかの設定オプションが必要です。 以下、それぞれの設定について見ていきます。
Payload URL
ペイロード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コンテンツタイプは、JSONペイロードをPOSTリクエストのボディとして直接配信します。application/x-www-form-urlencodedコンテンツタイプは、JSONペイロードをpayloadと呼ばれるフォームのパラメータとして送信します。
要求に最適なものを選んでください。 このチュートリアルでは、デフォルトのコンテントタイプをapplication/jsonにしておけば問題ありません。
Secret
webhookのシークレットを設定することで、ペイロードのURLに送信されるPOSTリクエストが、GitHub Enterprise Serverからのものであることが保証できます。 シークレットを設定すると、webhookのPOSTリクエスト中のX-Hub-Signatureヘッダを受信することになります。 署名ヘッダでシークレットを使用してwebhookのペイロードをセキュアに保つ方法に関する詳細については、「webhookをセキュアに保つ」を参照してください。
SSL verification
「ペイロードURL」がセキュアなサイト（HTTPS）の場合、SSL検証の設定をするオプションがあります。 「ペイロードURL」がセキュアでない（HTTP）場合、GitHubはこのオプションを表示しません。 デフォルトでは、webhookのペイロードを配信する際に、GitHubはWebサイトのSSL証明書を検証します。 SSL検証は、フックのペイロードがURLのエンドポイントにセキュアに配信されることを保証するための役に立ちます。 SSLを無効化するオプションもありますが、Enable SSL verification（SSLの検証の有効化）を選択しておくことをおすすめします。
Active
デフォルトでは、webhookの配信は「Active」です。 「Active」の選択を解除することで、webhookのペイロードの配信を無効化できます。
イベント
イベントは、webhookの中核です。 これらのwebhookは、リポジトリで特定のアクションが行われたときに動作し、それがサーバーのペイロードURLで受信され、処理が行われます。
webhookイベントと、それらのイベントがいつ動作するのかの完全なリストはwebhook APIリファレンスにあります。
Since our webhook is dealing with issues in a repository, we'll click Let me select individual events and then Issues. トリガーされたwebhookに対するIssueイベントを受信できるよう、必ずActiveを選択してください。 また、デフォルトオプションを使ってすべてのイベントを選択することもできます。
完了したら、Add webhook（webhookの追加）をクリックしてください。
Now that you've created the webhook, it's time to set up our local server to test the webhook. その方法はサーバーの設定を見てください。
Wildcard event
すべてのイベントに対してwebhookを設定するには、ワイルドカード（*）文字を使ってwebhookイベントを指定してください。 ワイルドカードイベントを追加すると、設定されたすべての既存のイベントはワイルドカードイベントで置き換えられ、サポートされるすべてのイベントについてペイロードが送信されます。 また、将来追加される可能性のある新しいイベントも自動的に受信されるようになります。