Webhook の基本を理解したので、Webhook で動作する独自の統合を構築するプロセスを見ていきましょう。 このチュートリアルでは、1日あたりに受け取るIssueの数に基づいて、リポジトリの人気の度合いをリストするリポジトリwebhookを作成します。
webhookの作成は、2ステップのプロセスです。 最初に、Webhook でリッスンするイベントを設定する必要があります。 その後、ペイロードを受信して管理するようにサーバーをセットアップします。
Webhook REST API を使用すると、リポジトリ、Organization、アプリ Webhook を管理できます。 この API を使用すると、Webhook の Webhook 配信を一覧表示したり、Webhook の個別の配信を取得して再配信したりできます。Webhook は、外部のアプリまたはサービスに統合できます。 REST API を使用して、Webhook の構成を変更することもできます。 たとえば、ペイロードURL、コンテントタイプ、SSLの検証、シークレットを変更できます。 詳細については、次を参照してください。
ローカルホストをインターネットに公開する
このチュートリアルでは、GitHub から Webhook イベントを受信するためにローカルサーバーを使います。
まず、GitHub がイベントを配信できるように、ローカル開発環境をインターネットに公開する必要があります。 これを行うには、ngrok を使います。
ngrok は無料で、主なオペレーティングシステムで利用できます。 詳細については、ngrok のダウンロード ページを参照してください。
ngrok をインストールしたら、コマンド ラインで ./ngrok http 4567 を実行してローカル ホストを公開できます。 4567 は、サーバーがメッセージを受信するポート番号です。 以下のような行が表示されるはずです。
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567*.ngrok.io URL をメモします。 webhookのセットアップで利用します。
Webhook を設定する
webhookは、Organizationもしくは特定のリポジトリにインストールできます。
webhookをセットアップするには、リポジトリもしくはOrganizationのsettings（設定）ページにアクセスしてください。 そこから [Webhook] 、 [Webhook の追加] の順にクリックします。
または、Webhook API を使用して Webhook をビルドして管理することもできます。
webhookには、利用を開始する前にいくつかの設定オプションが必要です。 以下、それぞれの設定について見ていきます。
ペイロード URL
ペイロード URL は、Webhook の POST 要求を受け取るサーバーの URL です。
このチュートリアル用にローカルで開発しているため、*.ngrok.io URL の後に /payload を設定します。 たとえば、http://7e9ea9dc.ngrok.io/payload のようにします。
Content type
webhookは、様々なコンテンツタイプを使って配信できます。
application/jsonのコンテンツ タイプは、POST要求の本文として JSON ペイロードを直接配信します。application/x-www-form-urlencodedのコンテンツ タイプは、payloadというフォーム パラメーターとして JSON ペイロードを送信します。
ニーズに最適なプリセットを選択してください。 このチュートリアルでは、application/json の既定のコンテンツ タイプで問題ありません。
Secret
Webhook のシークレットを設定することで、ペイロードの URL に送信される POST 要求が、GitHub Enterprise Server からのものであることを保証できます。 シークレットを設定すると、Webhook の POST 要求で X-Hub-Signature ヘッダーと X-Hub-Signature-256 ヘッダー が受信されます。 署名ヘッダーでシークレットを使用して Webhook のペイロードをセキュアに保つ方法について詳しくは、「Webhook のセキュリティ保護」を参照してください。
SSL の検証
「ペイロードURL」がセキュアなサイト（HTTPS）の場合、SSL検証の設定をするオプションがあります。 「ペイロードURL」がセキュアでない（HTTP）場合、GitHubはこのオプションを表示しません。 デフォルトでは、webhookのペイロードを配信する際に、GitHubはWebサイトのSSL証明書を検証します。 SSL検証は、フックのペイロードがURLのエンドポイントにセキュアに配信されることを保証するための役に立ちます。 SSL を無効化するオプションもありますが、 [SSL の検証の有効化] を選択しておくことをお勧めします。
アクティブ
デフォルトでは、webhookの配信は「Active」です。 「Active」の選択を解除することで、webhookのペイロードの配信を無効化できます。
イベント
イベントは、webhookの中核です。 これらのwebhookは、リポジトリで特定のアクションが行われたときに動作し、それがサーバーのペイロードURLで受信され、処理が行われます。
webhook イベントとそれらがいつ実行されるかの完全なリストについては、Webhook API のリファレンスを参照してください。
ここでの Webhook はリポジトリ内の Issue を扱うので、 [個別のイベントを選択する] をクリックしてから、 [Issue] をクリックします。 トリガーされた Webhook の発行イベントを受け取るには、[アクティブ] を選択します。 また、デフォルトオプションを使ってすべてのイベントを選択することもできます。
完了したら、 [Webhook の追加] をクリックします。
これでwebhookができたので、ローカルサーバーをセットアップしてwebhookをテストしましょう。 その方法については、サーバーの構成に進んでください。
ワイルドカードイベント
すべてのイベントに対して Webhook を設定するには、ワイルドカード (*) 文字を使って Webhook イベントを指定します。 ワイルドカードイベントを追加すると、設定されたすべての既存のイベントはワイルドカードイベントで置き換えられ、サポートされるすべてのイベントについてペイロードが送信されます。 また、将来追加される可能性のある新しいイベントも自動的に受信されるようになります。