GitHub Apps での Webhook の使用

Webhook と GitHub Apps

について

Webhook を使用すると、GitHub でイベント (例: 誰かがコミットをプッシュした、アプリからアクセスできるリポジトリで pull request を開いたなど) が発生したときに、GitHub App でリアルタイムに通知を受け取ることができます。 Webhook の詳細については、「webhook について」を参照してください。 GitHub App で Webhook を使用する方法を示すチュートリアルについては、「Webhook イベントに応答する GitHub App の構築」を参照してください。

GitHub で特定のイベントの Webhook を受け取り、それらに対して自動的にアクションを実行するように、GitHub App を構成することができます。 受け取ることができる Webhook の種類については、「Webhook のイベントとペイロード」を参照してください。

GitHub App で Webhook イベントを受け取るには、GitHub App 登録で Webhook を有効にし、GitHub からの Webhook ペイロードの送信先となる Webhook URL を指定する必要があります。

GitHub App が Webhook に応答する必要がない場合や、認証用にのみ使用される場合は、GitHub App 登録の Webhook 機能を無効にすることができます。 Webhook URL を指定する必要はありません。

GitHub App の登録の詳細については、「GitHub App の登録」を参照してください。 GitHub App 登録がサブスクライブする Webhook を変更する方法の詳細については、「GitHub App 登録の変更」を参照してください。

Webhook URL の選択

GitHub App 登録の Webhook をアクティブにする際には、Webhook URL を指定する必要があります。 Webhook URL とは、GitHub App に送信された Webhook イベント ペイロードを受け取る Web サーバーのアドレスのことです。 その後、サーバーでペイロードの内容に基づいてアクションを実行できるようになります。 GitHub App で発生する Webhook トラフィックの量に適した Web サーバーを選択する必要があります。

開発とテスト用の Webhook URL の選択

アプリの開発中とテスト中に、Smee などの Webhook ペイロード配信サービスを使用して、Webhook ペイロードをキャプチャし、ローカル開発環境に転送することができます。 Smee チャネルは認証されておらず、セキュリティで保護されていないため、運用環境のアプリケーションには Smee を使用しないでください。 または、ngrok、localtunnel、Hookdeck Console などのツールを使って、ローカル コンピューターをインターネットに公開してペイロードを受け取ることもできます。

Smee を使用した Webhook URL の作成

Smee を使用すると、ローカル開発をインターネットに公開することなく、GitHub で Webhook ペイロードを送信できる一意のドメインを作成できます。 Smee では、この一意のドメインを "Webhook プロキシ URL" と呼びます。 GitHub App の Webhook URL として Smee の Webhook プロキシ URL を使用できます。

1. Smee を使用して一意のドメインを作成するには、 https://smee.io に移動し、 [新しいチャネルを開始する] をクリックします。
2. Smee のチャネル ページで、[CLI を使用する] の下の指示に従って、Smee クライアントをインストールして実行します。
3. Smee Webhook URL を GitHub App に接続するには、GitHub App 登録ページの [Webhook URL] フィールドに一意の Smee ドメインを入力します。 詳細については、「GitHub App の登録」および「GitHub App 登録の変更」を参照してください。

運用環境用の Webhook URL の選択

受け取る Webhook トラフィックの量が少ない運用環境のアプリケーションについては、任意の動的アプリケーション サーバーにホストできます。 Webhook を処理するためのサーバー側コードでは、イベントを受け取り、その JSON ペイロードを逆シリアル化し、実行するアクション (データベースにデータを格納する、GitHub API を呼び出すなど) を決めることができます。

運用環境の大規模なアプリで大量の Webhook トラフィックを処理するには、専用サーバーで非同期 Webhook 処理を使用することを検討してください。 これは、キューを導入することで実現できます。これにより、Webhook ハンドラーからキューにデータがプッシュされ、イベントに基づいて別個のプロセスにより後続のアクションが実行されます。 さらに、Azure Functions、AWS Lambda、Hookdeck などのクラウド機能を使って、大量の Webhook イベントを処理するようにアプリをスケーリングすることができます。

Webhook シークレットを使用した Webhook のセキュリティ保護

ペイロードを受け取るようにサーバーを構成すると、サーバーに送信されるあらゆるペイロードをリッスンするようになります。 セキュリティ上の理由から、受信要求は発信元が GitHub の要求のみに制限する必要があります。 これを行うには、アプリの Webhook シークレットを作成します。

GitHub App の Webhook シークレットを作成するには、GitHub App 登録ページの [Webhook シークレット] にシークレット トークンを入力します。 エントロピーの高いランダムな文字列を選択してください。 詳細については、「GitHub App の登録」および「GitHub App 登録の変更」を参照してください。

アプリの Webhook シークレットを作成した後は、Webhook シークレット トークンを安全に格納して検証するようにサーバーを構成する必要があります。 詳しくは、「Webhook 配信を検証する」をご覧ください。

Webhook イベントのサブスクライブ

特定のイベントの Webhook ペイロードを受け取るために、GitHub App にサブスクライブすることができます。 GitHub App の登録で選択できる具体的な Webhook イベントは、アプリに対して選択したアクセス許可の種類によって決まります。 まず、アプリに付与するアクセス許可を選択する必要があります。これで、そのアクセス許可のセットに関連する Webhook イベントにアプリをサブスクライブできます。詳細については、「GitHub アプリのアクセス許可を選択する」を参照してください。

たとえば、リポジトリで新しいイシューが開かれるたびにアプリで Webhook イベント ペイロードを受け取るようにする場合は、まず、[リポジトリのアクセス許可] で [イシュー] にアクセスするためのアクセス許可をアプリに付与する必要があります。 これで、[イベントにサブスクライブする] で [イシュー] を選択できます。

各 Webhook イベントに必要なアクセス許可の詳細については、「Webhook のイベントとペイロード」を参照してください。