Webhook の使用に関するベスト プラクティス

サブスクライブするイベント数を最小にする

必要な Webhook イベントのみをサブスクライブしてください。 これにより、サーバーで実行する必要がある作業量が減ります。 イベントへのサブスクライブに関する詳細については、「webhookの作成」と「webhookの編集」を参照してください。

Webhook シークレットを使用する

Webhook シークレットはエントロピーの高いランダムな文字列にしてください。 サーバーがアクセスできる方法で Webhook シークレットを安全に格納してください。

HTTPS と SSL 検証を使用する

サーバーで HTTPS 接続が使用されていることを確認してください。 既定では、GitHub は Webhook のデリバリーの際に SSL 証明書を検証します。 GitHub では、SSL 検証を有効にしたままにすることをお勧めします。

GitHub の IP アドレスを許可する

サーバーの IP 許可一覧を設定し、GitHub が Webhook デリバリーに使用する IP アドレスを追加できます。 これにより、サーバーへのなりすまし要求をブロックできます。

GET /meta エンドポイントを使用して、GitHub の IP アドレスの現在の一覧を見つけることができます。 詳しくは、「メタデータ用 REST API エンドポイント」をご覧ください。 GitHub は IP アドレスを変更することがあるため、IP 許可一覧を定期的に更新してください。

詳しくは、「GitHubのIPアドレスについて」をご覧ください。

10 秒以内に応答する

Webhook デリバリーを受信してから 10 秒以内にサーバーが 2XX 応答を返すようにしてください。 サーバーの応答にそれ以上の時間がかかる場合、GitHub は接続を終了し、デリバリーが失敗したと見なします。

タイムリーに応答するために、Webhook ペイロードを非同期的に処理するキューを設定できます。 サーバーは、Webhook を受信したときに応答し、その後の Webhook デリバリーをブロックすることなく、バックグラウンドでペイロードを処理できます。 たとえば、Hookdeck などのサービスや、Resque (Ruby)、RQ (Python)、RabbitMQ (Java) などのライブラリを使用できます。

イベントの処理前にイベントのタイプとアクションを確認する

Webhook のイベントの種類は複数あり、イベントの多くには複数のアクション タイプがある可能性があります。 GitHub は、引き続き新しいイベントの種類と新しいアクションを既存のイベントの種類に追加します。 アプリケーションでは、ペイロードを処理する前に、Webhook ペイロードのイベントの種類とアクションを確認するようにしてください。 イベントの種類を決定するには、X-GitHub-Event 要求ヘッダーを使用します。 アクション タイプを決定するには、イベント ペイロードで最上位の action キーを使用します。

配信されなかった場合に再配信する

サーバーがダウンした場合は、サーバーが復帰したら、配信されなかった Webhook を再配信してください。 詳しくは、「Webhook の再配信」をご覧ください。

X-GitHub-Delivery ヘッダーを使用する

リプレイ攻撃では、不適切なアクターが Webhook 配信をインターセプトし、配信を再送信します。 リプレイ攻撃から保護するために、X-GitHub-Delivery ヘッダーを使用して各配信がイベント毎に一意であることを確認できます。

参考資料

• REST API を使用するためのベスト プラクティス
• GitHub App を作成するためのベスト プラクティス