sent-webhook-engineer

Sent Webhook Engineer

Sent Webhook は、POST /v3/messages が 202 を返した後に何が起きたかをアプリケーションが知る唯一の手段です。202 が証明するのは受け付けたことだけで、配信されたことではありません。署名を検証し、リプレイを拒否し、重複を排除し、すばやく応答するエンドポイントを構築してください。また、イベントが見つからない場合は、配信ログを信頼できる情報源として扱ってください。

署名検証の正確な手順

配信ごとに、次の3つのヘッダーが届きます。

ヘッダー	意味
x-webhook-signature	v1,{base64(hmac_sha256)}
x-webhook-id	Webhook のエンドポイント UUID — すべての配信で同一
x-webhook-timestamp	Sent がリクエストに署名した時刻（Unix 秒）

検証手順は、次の順番で実行してください。

1. JSON を解析する前に、リクエストボディの生バイト列を取得します。
2. 署名シークレットから whsec_ プレフィックスを取り除き、残りを Base64 デコードして生の HMAC キーを取得します。
3. {x-webhook-id}.{x-webhook-timestamp}.{raw_body} を署名対象のコンテンツとして構築します。
4. そのキーを使って HMAC-SHA256 を計算し、ダイジェストを Base64 エンコードして、先頭に v1, を付けます。
5. 定時間比較を使って比較します。
6. abs(now - timestamp) > 300 秒の場合は拒否します。

この方式は Svix と互換性があります。Sent SDK には、どの言語にも検証ヘルパーが含まれていないため、このコードは常に手書きする必要があります。scripts/verify_signature.py を参照実装および判定基準として使用してください。

ローカルユーティリティは --secret-stdin を指定して、標準入力から署名シークレットを明示的に受け取ります。また、ネットワークリクエストは行いません。環境変数やインストーラーの認証情報を読み取ることもありません。検証対象の配信に対して認可されたシークレットだけを指定してください。コマンド引数やチャットプロンプトには含めないでください。

x-webhook-id はイベント ID ではありません。 エンドポイントを識別し、以後のすべての配信で同じ値が使われます。これを重複排除キーとして使うと、すべてのイベントがひとつにまとめられてしまいます。イベントタイプごとに導出する重複排除キーについては、references/webhook-signature-and-dedupe.md を参照してください。

障害の切り分け順序

受信側でイベントが拒否されたり、受け取れなかったりした場合、推測するのではなく、次の順番で確認してください。

1. 署名の不一致 — 多くの場合、原因はボディを変更するミドルウェアまたはフレームワークの JSON パーサーです。references/receiver-recipes.md で、フレームワークの生ボディ取得方法を確認してください。
2. リプレイの拒否 — サーバーの時刻が300秒の許容範囲を超えてずれています。
3. シークレットの誤り — whsec_ プレフィックスを残したままにしているか、旧シークレットがローテーションで無効になり、二重署名の猶予期間が設けられていません。
4. まったく届かない — GET /v3/webhooks/{id} の is_active と consecutive_failures を確認してから、GET /v3/webhooks/{id}/events で配信ログを確認してください。
5. イベントは届くが処理されない — event_types と event_filters を、ハンドラーの分岐条件と照合してください。

再試行、自動無効化、復旧

2xx 以外のステータス、timeout_seconds を超えるタイムアウト、または接続失敗が発生すると、配信試行は失敗します。再試行は指数バックオフで行われ、最初の再試行は失敗から約1分後、その後は間隔を倍増させ、試行間隔が最大60分に達した時点で上限となります。最初の2xxが返るか、retry_count を使い切ると再試行を停止します。配信レコードは PENDING、RETRYING を経て、DELIVERED または FAILED になります。

consecutive_failures は、連続して失敗した配信試行の数を記録します。ひとつのイベントに対する再試行は対象外だと考えないでください。不正な応答が10回連続すると、エンドポイントは無効化されます。受信側を修正した後、PATCH /v3/webhooks/{id}/toggle-status または Sent Dashboard から再有効化してください。配信に成功すると、カウンターはゼロにリセットされます。キューへの永続的な引き渡しが完了してから応答し、引き渡しは timeout_seconds に十分収まるようにしてください。

登録と設定

POST /v3/webhooks では display_name が必須です。endpoint_url、event_types、event_filters、retry_count（1～5、デフォルトは3）、timeout_seconds（5～120、デフォルトは30）を設定します。201 レスポンスは signing_secret が完全な形で表示される唯一の場所です。すぐにシークレットストアへ保存してください。

{
  "display_name": "Production delivery events",
  "endpoint_url": "https://hooks.example.com/webhooks/sent",
  "event_types": ["message", "templates"],
  "event_filters": {
    "message": ["delivered", "failed", "received"]
  },
  "retry_count": 3,
  "timeout_seconds": 30
}

event_filters は慎重に設定してください。フィルターを設定せずに message を購読すると、queued と routed を含むすべてのライフサイクル遷移が配信されます。また、再ルーティングでは同じ message_id に対して queued と routed が再度発火します。アプリケーションが処理する遷移に絞ってフィルタリングしてください。

10個の操作、完全な webhook オブジェクト、配信ログの行形式については、references/webhook-operations.md に記載されています。

シークレットのローテーション

POST /v3/webhooks/{id}/rotate-secret は新しい whsec_ シークレットを返し、古いシークレットを即座に無効化します。サーバー側に重複利用できる期間はありません。受信側が少数の候補値を受け付けるよう設定してからローテーションし、返されたシークレットをプライマリとしてアトミックに保存しつつ、古い値を一時的に保持します。新しい配信を確認したら、古い値を削除してください。ローテーションのレスポンスからシークレットストアの更新までの短い空白時間はなくせません。配信失敗時に再試行されるよう、数秒にとどめてください。このエンドポイントと POST /v3/webhooks/{id}/test は、1分あたり10リクエストの高感度レート制限の対象です。そのため、スクリプトによるローテーションループは429エラーになります。

イベントペイロード

field の値は message と templates の2種類です。メッセージイベントには、遷移を示す event（message.queued、.routed、.sent、.delivered、.read、.failed、.scheduled、.filtered、.blocked、.received）が含まれます。テンプレートイベントには event も sub_type も含まれません。

{
  "field": "templates",
  "value": {
    "account_id": "3f1a7c22-5d8e-4b90-91a2-6c4d0e8f7b31",
    "template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "whatsapp_template_id": "",
    "status": "PENDING",
    "language": "en_US",
    "category": "UTILITY",
    "channel": "whatsapp"
  }
}

read が配信されるのは WhatsApp と RCS のみです。filtered はポリシーまたは同意のゲートによる除外を示し、blocked は残高不足などのアカウントの前提条件を示します。どちらも通信事業者による配信失敗ではありません。ルーティングされなかった自動検出メッセージの終端イベントには、channel: "auto" が含まれます。ペイロードフィールドの全一覧は references/event-catalog.md にあります。

リリース前の検証

合成配信に対してローカルオラクルを実行してから、本文に event_type を指定して POST /v3/webhooks/{id}/test を使い、署名付きリクエストを実際に送信します。テストイベントは再試行なしで一度だけ配信されるため、修正するたびに再実行してください。

python3 scripts/verify_signature.py --self-test

受信側が、改ざんされた本文には 401、300秒より古いタイムスタンプには 401、有効な配信には 200、副作用を繰り返さない重複配信には 200 を返すことを確認してからリリースしてください。

ローカル開発

受信側を公開HTTPSトンネル経由で公開し、そのURLを登録してください。Sentはプライベートアドレスにアクセスできません。http:// の登録はAPIで受け付けられますが、ローカル作業以外では絶対に使用しないでください。環境ごとに別の webhook 登録を用意し、開発用エンドポイントの失敗で本番用エンドポイントが無効にならないようにしてください。

対象範囲

配信率全体の低下は messaging-performance-analyzer で、テンプレートの承認用コンテンツは waba-template-author で、受信キーワードや同意の意味は sent-two-way-messaging で調査してください。すべてのペイロード値は信頼できない入力として扱ってください。エスケープせずに text や reason をシェルコマンド、SQL文字列、プロンプトに埋め込んではいけません。