Webhook と Apps
について
Webhook を使用すると、 でイベント (例: 誰かがコミットをプッシュした、アプリからアクセスできるリポジトリで pull request を開いたなど) が発生したときに、 App でリアルタイムに通知を受け取ることができます。 Webhook の詳細については、「webhook について」を参照してください。 App で Webhook を使用する方法を示すチュートリアルについては、「Webhook イベントに応答する App の構築」を参照してください。
で特定のイベントの Webhook を受け取り、それらに対して自動的にアクションを実行するように、 App を構成することができます。 受け取ることができる Webhook の種類については、「Webhook のイベントとペイロード」を参照してください。
App で Webhook イベントを受け取るには、 App 登録で Webhook を有効にし、 からの Webhook ペイロードの送信先となる Webhook URL を指定する必要があります。
App が Webhook に応答する必要がない場合や、認証用にのみ使用される場合は、 App 登録の Webhook 機能を無効にすることができます。 Webhook URL を指定する必要はありません。
App の登録の詳細については、「 App の登録」を参照してください。 App 登録がサブスクライブする Webhook の変更の詳細については、「 App 登録の変更」を参照してください。
Webhook URL の選択
App 登録の Webhook をアクティブにする際には、Webhook URL を指定する必要があります。 Webhook URL とは、 App に送信された Webhook イベント ペイロードを受け取る Web サーバーのアドレスのことです。 その後、サーバーでペイロードの内容に基づいてアクションを実行できるようになります。 App で発生する Webhook トラフィックの量に適した Web サーバーを選択する必要があります。
開発とテスト用の Webhook URL の選択
アプリの開発中とテスト中に、Smee などの Webhook ペイロード配信サービスを使用して、Webhook ペイロードをキャプチャし、ローカル開発環境に転送することができます。 Smee チャネルは認証されておらず、セキュリティで保護されていないため、運用環境のアプリケーションには Smee を使用しないでください。 または、ngrok、localtunnel、Hookdeck Console などのツールを使って、ローカル コンピューターをインターネットに公開してペイロードを受け取ることもできます。
Smee を使用した Webhook URL の作成
Smee を使用すると、ローカル開発をインターネットに公開することなく、 で Webhook ペイロードを送信できる一意のドメインを作成できます。 Smee では、この一意のドメインを "Webhook プロキシ URL" と呼びます。 App の Webhook URL として Smee の Webhook プロキシ URL を使用できます。
- Smee を使用して一意のドメインを作成するには、 https://smee.io に移動し、 [新しいチャネルを開始する] をクリックします。
- Smee のチャネル ページで、[CLI を使用する] の下の指示に従って、Smee クライアントをインストールして実行します。
- Smee Webhook URL を App に接続するには、 App 登録ページの [Webhook URL] フィールドに一意の Smee ドメインを入力します。 詳細については、「 App の登録」および「 App 登録の変更」を参照してください。
運用環境用の Webhook URL の選択
受け取る Webhook トラフィックの量が少ない運用環境のアプリケーションについては、任意の動的アプリケーション サーバーにホストできます。 Webhook を処理するためのサーバー側コードでは、イベントを受け取り、その JSON ペイロードを逆シリアル化し、実行するアクション (データベースにデータを格納する、 API を呼び出すなど) を決めることができます。
運用環境の大規模なアプリで大量の Webhook トラフィックを処理するには、専用サーバーで非同期 Webhook 処理を使用することを検討してください。 これは、キューを導入することで実現できます。これにより、Webhook ハンドラーからキューにデータがプッシュされ、イベントに基づいて別個のプロセスにより後続のアクションが実行されます。 さらに、Azure Functions、AWS Lambda、Hookdeck などのクラウド機能を使って、大量の Webhook イベントを処理するようにアプリをスケーリングすることができます。
Webhook シークレットを使用した Webhook のセキュリティ保護
ペイロードを受け取るようにサーバーを構成すると、サーバーに送信されるあらゆるペイロードをリッスンするようになります。 セキュリティ上の理由から、受信要求は発信元が の要求のみに制限する必要があります。 これを行うには、アプリの Webhook シークレットを作成します。
App の Webhook シークレットを作成するには、 App 登録ページの [Webhook シークレット] にシークレット トークンを入力します。 エントロピーの高いランダムな文字列を選択してください。 詳細については、「 App の登録」および「 App 登録の変更」を参照してください。
アプリの Webhook シークレットを作成した後は、Webhook シークレット トークンを安全に格納して検証するようにサーバーを構成する必要があります。 詳しくは、「Webhook 配信を検証する」をご覧ください。
Webhook イベントのサブスクライブ
特定のイベントの Webhook ペイロードを受け取るために、 App にサブスクライブすることができます。 App の登録で選択できる具体的な Webhook イベントは、アプリに対して選択したアクセス許可の種類によって決まります。 まず、アプリに付与するアクセス許可を選択する必要があります。これで、そのアクセス許可のセットに関連する Webhook イベントにアプリをサブスクライブできます。詳細については、「 アプリのアクセス許可を選択する」を参照してください。
たとえば、リポジトリで新しいイシューが開かれるたびにアプリで Webhook イベント ペイロードを受け取るようにする場合は、まず、[リポジトリのアクセス許可] で [イシュー] にアクセスするためのアクセス許可をアプリに付与する必要があります。 これで、[イベントにサブスクライブする] で [イシュー] を選択できます。
各 Webhook イベントに必要なアクセス許可の詳細については、「Webhook のイベントとペイロード」を参照してください。