Skip to main content

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

Webhook を使用する場合のセキュリティとパフォーマンスを向上させるには、次のベスト プラクティスに従います。

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

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

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

Webhook に Webhook シークレットを設定し、各 Webhook デリバリーのシグネチャがシークレットと一致することを確認してください。 これは、Webhook デリバリーが GitHub からのものであることを確認するのに役立ちます。 詳しくは、「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 ヘッダーを使用して各配信がイベント毎に一意であることを確認できます。

: 再配信を要求した場合、 X-GitHub-Delivery ヘッダーは元の配信と同じになります。

参考資料