webhookの基礎を理解したので、webhookで動作する独自のインテグレーションオン構築プロセスを見ていきましょう。 このチュートリアルでは、1日あたりに受け取るIssueの数に基づいて、リポジトリの人気の度合いをリストするリポジトリwebhookを作成します。
webhookの作成は、2ステップのプロセスです。 まず、webhookをGitHub Enterprise Serverを通じてどのように動作させたいのかをセットアップする必要があります。これはすなわち、どのイベントを待ち受けるのかということです。 その後、ペイロードを受信して管理するようにサーバーをセットアップします。
The webhook REST APIs enable you to manage repository, organization, and app webhooks. You can also use the REST API to change the configuration of the webhook. たとえば、ペイロードURL、コンテントタイプ、SSLの検証、シークレットを変更できます。 詳しい情� �については、以下を参照してく� さい。
ローカルホストをインターネットに公開する
このチュートリアルでは、GitHubからメッセージを受信するためにローカルサーバーを使用します。 そのためには、まずローカル開発環境をインターネットに公開する必要があります。 そのためにngrokを使用しましょう。 ngrokは無料で、主要なオペレーティングシステ� で利用できます。 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は、サーバーがメッセージを受信するポート番号です。 以下のような行が表示されるはずです。
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567
この *.ngrok.io
URL はメモしてく� さい。 webhookのセットアップで利用します。
webhookのセットアップ
webhookは、Organizationもしくは特定のリポジトリにインストールできます。
webhookをセットアップするには、リポジトリもしくはOrganizationのsettings(設定)ページにアクセスしてく� さい。 そこからWebhooksをクリックし、続いてAdd webhook(webhookの追� )をクリックしてく� さい。
あるいは、Webhooks APIを通じてwebhookの構築と管理を行うこともできます。
webhookには、利用を開始する前にいくつかの設定オプションが必要です。 以下、それぞれの設定について見ていきます。
Payload URL
ペイロードURLは、webhookのPOST
リクエストを受信するサーバーのURLです。
チュートリアルではローカルで開発をしているので、*.ngrok.io
URLの後に /payload
を付けましょう。 たとえば、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からのものであることが保証できます。 When you set a secret, you'll receive the X-Hub-Signature
and X-Hub-Signature-256
headers in the webhook POST
request. 署名ヘッダでシークレットを使用してwebhookのペイロードをセキュアに保つ方法に関する詳細については、「webhookをセキュアに保つ」を参照してく� さい。
SSL の検証
「ペイロード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リファレンスにあります。
ここでのwebhookはリポジトリ内のIssueを扱うので、Let me select individual events(個別のイベントを選択する)をクリックし、そしてIssueをクリックしてく� さい トリガーされたwebhookに対するIssueイベントを受信できるよう、必ずActiveを選択してく� さい。 また、デフォルトオプションを使ってすべてのイベントを選択することもできます。
完了したら、Add webhook(webhookの追� )をクリックしてく� さい。
これでwebhookができたので、ローカルサーバーをセットアップしてwebhookをテストしましょう。 その方法はサーバーの設定を見てく� さい。
ワイルドカードイベント
すべてのイベントに対してwebhookを設定するには、ワイルドカード(*
)文字を使ってwebhookイベントを指定してく� さい。 ワイルドカードイベントを追� すると、設定されたすべての既存のイベントはワイルドカードイベントで置き換えられ、サポートされるすべてのイベントについてペイロードが送信されます。 また、将来追� される可能性のある新しいイベントも自動的に受信されるようになります。