webhookの作成

Webhook の基本を理解したので、Webhook で動作する独自の統合を構築するプロセスを見ていきましょう。このチュートリアルでは、1日あたりに受け取るIssueの数に基づいて、リポジトリの人気の度合いをリストするリポジトリwebhookを作成します。

webhookの作成は、2ステップのプロセスです。最初に、Webhook でリッスンするイベントを設定する必要があります。その後、ペイロードを受信して管理するようにサーバーをセットアップします。

REST API を利用し、リポジトリ、組織、アプリ Webhook を管理できます。 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

注: 現在、GitHub Webhook では IPv6 はサポートされていませんが、今後サポートされる予定です。 /meta REST API エンドポイントは、その遷移を有効にするための IPv6 範囲を返します。

ペイロード 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 イベントを指定します。ワイルドカードイベントを追加すると、設定されたすべての既存のイベントはワイルドカードイベントで置き換えられ、サポートされるすべてのイベントについてペイロードが送信されます。また、将来追加される可能性のある新しいイベントも自動的に受信されるようになります。

webhookの作成

この記事の内容