Webhookとは？イベント、配信、セキュリティ、デザイン

Scrapeless Scraping APIは、非同期スクレイピングタスクが完了したときに設定されたWebhook URLにHTTP POSTリクエストを送信できます。

Webhookとは？

Webhookは、あるシステムがイベント後に別のシステムにHTTPリクエストを送信するメカニズムです。受信アプリケーションはエンドポイントURLを登録し、しばしばタスク完了、請求書支払い、レコード更新、デプロイメント完了、またはメッセージ配信などのイベントタイプを選択します。イベントが発生すると、プロデューサーはそのエンドポイントにイベントデータとメタデータを呼び出します。

Webhookは時にはリバースAPIコールとして説明されます。通常のAPIのやり取りでは、コンシューマーが状態を読み取ったり変更したりするためにリクエストを開始します。Webhookでは、プロデューサーがコンシューマーに通知するリクエストを開始します。受信URLは依然としてHTTPエンドポイントであり、実装は一般的なAPIセキュリティ、検証、可用性、および観測性の慣行を適用する必要があります。

その 標準Webhook仕様 は、安全で相互運用可能なWebhook配信のための慣例を収集します。ペイロード、イベントメタデータ、署名、および運用上の動作をカバーしながら、各提供者は依然として独自のイベントタイプおよび契約を定義します。

Webhookの動作

1. コンシューマーはエンドポイントを登録します。 登録はダッシュボードまたはAPIで行われることがあり、通常はサブスクリプションに秘密を関連付けます。
2. コンシューマーはイベントを選択します。 狭いサブスクリプションは不要なトラフィックとデータ露出を減少させます。
3. プロデューサーはイベントを記録します。 ドメインアクションは、安定した識別子を持つ不変のイベントまたは配信タスクを生成します。
4. プロデューサーはペイロードを構築します。 イベントタイプ、イベントID、発生時間、スキーマバージョン、および関連データをシリアライズします。
5. プロデューサーは配信に署名します。 署名は生のボディと、文書化されたスキームに基づく新鮮さのメタデータをカバーします。
6. プロデューサーはHTTPリクエストを送信します。 JSONボディを持つPOSTが一般的ですが、契約がメソッドとメディアタイプを決定します。
7. コンシューマーはそれを検証し、記録します。 エンドポイントは、イベントを受け入れる前にトランスポート、署名、タイムスタンプ、イベントID、スキーマ、およびサブスクリプションをチェックします。
8. コンシューマーは確認します。 耐久的な受け入れ後に文書化された成功ステータスを返し、より長い処理をキューまたはワーカーを通じて実行します。

Webhookペイロードの例

小さなイベントエンベロープは、メタデータをドメインデータから分離することができます：

{
  "id": "evt_7f32",
  "type": "task.completed",
  "occurred_at": "2026-08-24T03:10:00Z",
  "version": "1",
  "data": {
    "task_id": "task_b18c",
    "status": "completed"
  }
}

表示される日付は、出版スタンプではなく説明的なコード定数です。イベントIDは重複排除をサポートし、タイプはハンドラーとスキーマを選択し、発生時間はドメインイベントを説明し、バージョンはペイロードの進化を制御します。配信時間は、署名スキームがそれを使用する場合、リクエストメタデータに含まれます。

Webhookボディが現在のリソース全体を含むと仮定しないでください。一部のプロデューサーはIDを持つ薄い通知を送り、その後コンシューマーはAPIを呼び出して承認された現在の状態を取得します。他のプロデューサーは、完全なイベントスナップショットを送信します。契約には、ペイロードがイベント、イベント後のリソース、またはポインターを表すかどうかが記述される必要があります。

Webhook対ポーリング、API、およびWebSocket

重要なシステムはしばしばパターンを組み合わせます。ウェブフックは迅速な通知を提供し、定期的な照合プロセスは現在のAPI状態とローカル状態を比較します。ウェブフックはレイテンシを改善し、照合はギャップやポリシーの変更を検出しますが、1つの配信経路が完璧であると仮定しません。

ウェブフック署名の仕組み

共有秘密設計は、通常、正確な生リクエストボディに加えて、配信タイムスタンプやイベントIDなどのメタデータに対するキー付きハッシュを使用します。HMACはメッセージ認証のための標準的な構造で、 RFC 2104で定義されています。他のプロバイダーは非対称署名を使用して、消費者が公衆鍵で検証できるようにします。

消費者はプロバイダーのバイト単位のアルゴリズムを遵守しなければなりません。署名ヘッダーをそのバージョン形式に従って解析し、署名されたコンテンツを正確に再構築し、予想される値を計算し、定数時間関数を介して比較します。検証の後にのみ、コードはJSONペイロードを解析し、信頼すべきです。

フレームワークのミドルウェアは、JSONを解析し再シリアル化する際に検証を中断する可能性があります。ホワイトスペース、プロパティの順序、エスケープ、数値書式は、データが等価に見えても変更される可能性があります。通常のボディ解析の前に生ボディバイトをキャプチャし、その後確認済みのバイトをJSONパーサーに渡します。

リプレイ保護と冪等性

署名が期限切れにならない限り、有効な古いウェブフックは悪意を持ってリプレイされる可能性があります。署名スキームにはしたがって、配信タイムスタンプまたは他の新鮮さの値が含まれています。受信者は、小さな文書化された時間枠だけを受け入れ、時計を同期させる必要があります。タイムスタンプのチェックは、イベントIDの重複排除を置き換えるのではなく、補足するものです。

冪等性とは、同じ論理イベントを複数回処理しても、一度処理した時と同じビジネス結果を生成することを意味します。生産者の安定したイベントIDを一意性制約を持つテーブルに保存し、ビジネス変更を適用する同じトランザクションで理想的にします。ビジネス更新の前にイベントを「視認済み」とマークすると、そのアクション間でプロセスが停止した場合に作業が失われる可能性があります。

いくつかの操作は自然に冪等であり、たとえばレコードのステータスを特定のバージョンに設定することなどです。他のものは、残高を増やしたりメッセージを送信したりするのに、イベントIDに結び付けられた冪等性レコードが必要です。ペイロードをハッシュ化するのではなく、生産者の文書化された識別子によって重複排除してください。なぜなら、2つの正当なイベントが同一のボディを持つ場合があるからです。

順序とイベントバージョン

配信順は発生順と異なる場合があり、イベントは別々のワーカー、リージョン、またはキューを通過する可能性があるためです。新しいアップデートが古いものよりも先に到着することがあります。消費者は、プロデューサーがサブスクリプションのために明示的に保証しない限り、到着順をビジネスオーダーとして扱うべきではありません。

定義された意味論を持つリソースバージョン、シーケンス、またはイベント発生時間を含めます。状態の更新は、そのバージョンがローカルバージョンよりも新しい場合にのみ適用します。状態スナップショットではなく不変のアクションを表すイベントに対しては、ドメインによって確立されたイベントシーケンスルールを保持します。

スキーマバージョンはリソースバージョンとは別です。スキーマバージョンはペイロードの形状を説明し、リソースバージョンは特定のエンティティの状態を説明します。概念を明確に区別することで、ペイロード形式の変更が新しいビジネスレコードのように見えることを防ぎます。

最初に確認し、キューを介して処理する

ウェブフックエンドポイントは制限された作業を行うべきです：要求サイズを強制し、署名を確認し、封筒を検証し、イベントIDを予約し、受け入れられたイベントを保存またはキューに追加し、文書化された成功応答を返します。遅いデータベース結合、外部API呼び出し、ファイル生成、メール送信はワーカーに属します。

耐久性のある受け入れは重要です。イベントが記録される前に成功を返すと、プロセスが停止した場合に失われます。応答する前に、すべてのダウンストリームアクションを待つことは、プロデューサーに接続を保持させる必要があり、エンドポイントが応答期限を超えると再配信を引き起こす可能性があります。

キューのメッセージには確認済みのイベント、サブスクリプションクコンテキスト、安全なトレース識別子が含まれているべきです。署名確認に使用される秘密は、キューペイロードには含まれません。

エンドポイント登録セキュリティ

ユーザーが任意のウェブフックURLを登録できる場合、生産者はユーザー入力に基づいて行動するHTTPクライアントになります。システムはサーバーサイドリクエストフォージェリから保護する必要があります。 OWASP SSRF防止チェックシート では許可リストとネットワーク層の制御を説明しています。

公のエンドポイントにはHTTPSを要求し、宛先を解決して検証し、ループバック、リンクローカル、プライベート、メタデータ、内部サービスの範囲をブロックし、選択されたポリシーに従ってリダイレクトやDNS解決後に再度チェックを適用します。ポート、メソッド、レスポンスバイト、接続時間、リダイレクト動作を制限します。

登録時にチャレンジまたは署名付きハンドシェイクを通じてエンドポイントの所有権を確認します。ウェブフックの応答ボディは信頼できないものとして扱い、配信エラーメッセージを通じて内部ネットワークの詳細を公開しないでください。

一般的なウェブフックのユースケース

可観測性と運用

イベントID、サブスクリプションID、イベントタイプ、スキーマバージョン、受信時間、検証決定、確認ステータス、処理状態、安全なコリレーション識別子を追跡します。署名シークレット、完全な認可ヘッダー、機密ペイロードフィールドはログに記録しないでください。

受け入れ遅延、キュー遅延、処理時間、重複率、署名の失敗、無効なスキーマ、古いタイムスタンプ、および順序の競合を測定します。受け入れたイベントが後で失敗した場合に一般的な成功メトリックに消えないように、プロデューサーの配信健康状態と消費者のビジネス処理健康状態を分けてください。

イベントIDで検索でき、編集された配信履歴を表示できる制御された管理ビューを提供します。運用チームは、資格情報や完全な機密本文を公開せずに欠落した状態変化を診断するための十分な証拠が必要です。

Webhookデザインチェックリスト

1. 安定したイベントタイプとIDを定義します。 ペイロードがイベント、スナップショット、またはポインタであるかどうかを文書化します。
2. スキーマのバージョンを管理します。 新しいオプションフィールドおよびイベント改訂の互換性ルールを定義します。
3. 生データと新鮮なメタデータに署名します。 正確な検証手順を公開し、シークレットの置き換えをサポートします。
4. エンドポイントのセキュリティを強化します。 所有権を確認し、SSRFの宛先をブロックします。
5. 冪等性を受け入れます。 一意のイベントIDとトランザクション的に安全な重複排除レコードを使用します。
6. 耐久性のある受け入れ後に確認します。 長い作業をキューに移動します。
7. 繰り返しと再順序を期待します。 到着順の仮定ではなく、リソースバージョンと調整を使用します。
8. 可観測性データを編集します。 秘密や機密ペイロードフィールドをログやサポートツールに含めないようにします。

結論

WebhookはイベントをHTTP通知に変換し、統合に低遅延の更新を提供します。HTTP呼び出しは簡単な部分です。生データの署名を確認し、新鮮さを強制し、イベントIDで重複排除し、再順序を処理し、耐久性のある受け入れ後にのみ確認し、キューを通じて処理し、SSRFからエンドポイントの登録を保護し、重要な状態を調整します。これらの制御は、コールバックを信頼できる統合境界に変えます。