Webhook の基本を理解したので、Webhook で動作する独自の統合を構築するプロセスを見ていきましょう。 このチュートリアルでは、1日あたりに受け取るIssueの数に基づいて、リポジトリの人気の度合いをリストするリポジトリwebhookを作成します。
webhookの作成は、2ステップのプロセスです。 まず、webhookをGitHub Enterprise Serverを通じてどのように動作させたいのかをセットアップする必要があります。これはすなわち、どのイベントを待ち受けるのかということです。 その後、ペイロードを受信して管理するようにサーバーをセットアップします。
Webhook REST API を使用すれば、リポジトリ、組織、アプリ Webhook の管理ができます。REST API を使用して、Webhook の構成を変更することもできます。 たとえば、ペイロードURL、コンテントタイプ、SSLの検証、シークレットを変更できます。 詳細については、次を参照してく� さい。
ローカルホストをインターネットに公開する
このチュートリアルでは、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 イベントを指定します。 ワイルドカードイベントを追� すると、設定されたすべての既存のイベントはワイルドカードイベントで置き換えられ、サポートされるすべてのイベントについてペイロードが送信されます。 また、将来追� される可能性のある新しいイベントも自動的に受信されるようになります。