Webhookは、特定のイベントが発生したときにサービスが登録したURLに送信するHTTPリクエストです。これにより、APIを何度も呼び出して新しいデータが利用可能かどうかを確認するのではなく、システムがリアルタイムでデータを受信できます。データパイプラインでは、ソースがイベントを報告するとすぐにジョブが反応できることを意味します。

例えば、決済プラットフォームのStripeは、HTTPS経由でエンドポイントにJSONペイロードとしてWebhookイベントを送信します。エンドポイントはPOSTリクエストを受け入れ、受信したイベントデータを処理する必要があります。

Webhook配信の仕組み

Stripeのドキュメントは、主なメカニズムを示しています:

  • 登録: エンドポイントURLを登録します。ライブモードでは、Stripeは公開アクセス可能なHTTPS URLを要求します。
  • 迅速な確認: エンドポイントは、タイムアウトを引き起こす可能性のある複雑なロジックの前に、迅速に2xxステータスコードを返す必要があります。
  • 再試行: 配信が失敗した場合、Stripeはライブモードで最大3日間、指数バックオフで再試行します。
  • 順序: Stripeは、イベントが作成された順序で到着することを保証しません。

Webhookエンドポイントのセキュリティ

  • 署名の確認: Stripeは、各イベントにSHA-256を使用したHMACで署名し、Stripe-Signatureヘッダーに署名を含めます。
  • リプレイのブロック: 署名されたペイロードにはタイムスタンプが含まれているため、古すぎるイベントを拒否できます。
  • 重複の処理: エンドポイントは、同じイベントを複数回受信する可能性があります。処理されたイベントIDをログに記録し、重複をスキップします。
  • 送信者のホワイトリスト: Stripeは、ファイアウォールを制限できる公開リストのIPアドレスからWebhookを送信します。

一般的なWebhookの使用例

  • コードとデプロイ: GitHubは、サブスクライブしたリポジトリイベントのために、あなたのURLにHTTP POSTペイロードを送信します。そのドキュメントには、CIビルドの開始、外部の問題トラッカーの更新、バックアップミラーのリフレッシュ、プロダクションサーバーへのデプロイなどの使用例が記載されています。
  • 支払い: StripeのWebhookを使用すると、銀行が支払いを確認したり、顧客が請求に異議を唱えたり、定期的な支払いが成功したりするなどの非同期イベントに応答できます。
  • 必要なものだけを購読: Stripeは、余分またはすべてのイベントをリッスンすることを避けるようにアドバイスしています。これはサーバーに過度の負担をかけるからです。

関連用語