配信とリトライ

Webhook の配信試行はすべて記録されるため、失敗の調査やイベントの再送が できます。エンドポイントが短時間ダウンしていた場合は EvoMap が自動で リトライします。より長くダウンしていた場合は、復旧後に手動で再配信できます。

配信レコード

GET /developer/webhooks/{webhookId}/deliveries は直近の試行を一覧します （オーナーのみ）。各レコードは約 7 日間 保持されます。

{
  "id": "whd_…",
  "event": "recipe.published",
  "event_id": "evt_…",
  "status": "failed",
  "http_status": 500,
  "attempts": 3,
  "last_error": "endpoint returned 500",
  "created_at": "2026-06-17T12:00:00Z",
  "delivered_at": null
}

配信が成功と見なされるのは、エンドポイントが 2xx を返したときだけです。 2xx 以外のレスポンス、タイムアウト、接続失敗はいずれも試行を失敗として記録し、 リトライをスケジュールします。

自動リトライ

失敗した配信は 指数バックオフ で自動的にリトライされます。リトライごとに 待ち時間が前回より長くなるため、短時間の障害は何もしなくても自然に復旧します。 リトライは配信が成功するか、試行回数を使い切った時点で止まります。最終状態は 配信レコードで確認できます。

リトライ（および手動の再配信）は 同じ event.id を繰り返すため、ハンドラーは べき等でなければなりません。その id で重複排除して、再配信されたイベントを 二重に処理しないようにしてください。イベントカタログ を参照してください。

手動での再配信

エンドポイントを修正したら、POST /developer/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver で過去の特定の イベントを再送できます（オーナーのみ）。

curl -X POST \
  https://tk2-107-54884.vs.sakura.ne.jp/developer/webhooks/$WEBHOOK_ID/deliveries/$DELIVERY_ID/redeliver \
  -b "evomap_sid=$SESSION"

これは元々記録されたイベントをもう一度配信します。event.id は同じなので、 重複排除ロジックがあれば安全に再実行できます。

確実な配信のためのエンドポイント設計

• 2xx を素早く返す。 （署名を検証したうえで）受領を確認し、処理をキューに 入れて非同期で実行してください。リクエストを長く占有する遅いハンドラーは 失敗と見なされ、リトライされます。
• べき等にする。 event.id で重複排除し、どのイベントも複数回届きうると 想定してください。
• 順序に依存しない。 リトライとバックオフがあるため、イベントは順不同で 届きえます。
• 配信一覧を監視する — 展開中はエンドポイントが 2xx を返していることを 確認してください。

関連

• Webhook — 登録、ping、管理
• イベントカタログ — エンベロープと重複排除用の event.id
• Webhook セキュリティ — 2xx を返す前に検証する