Webhookは「送って終わり」ではなく、小さな分散システムです。失敗パターンを先に潰し、再実行・監視・安全性まで含めて安定運用するためのチェックリストをまとめます。
このページはAI自動化ワークフローの実装判断に役立つよう、公式ドキュメント、価格ページ、実際の運用課題をもとに更新します。
Webhookの多くは「イベントが起きたら、指定URLにPOSTする」という単純な仕組みに見えます。しかし現実には、タイムアウト、再試行、重複、署名検証、順序入れ替わりなどが起きるため、失敗を前提にした作りにしないと安定しません。
n8n / Make / Zapier のような自動化ツールは便利ですが、エラー時の挙動（再試行、部分失敗、レート制限、キューの有無）がツールやプランによって変わります。最初に「何が起きたら失敗とみなすか」を決めておくと、復旧が速くなります。
原因は大きく「相手が送れていない」「こちらが受け取れていない」「受け取ったが処理できていない」に分かれます。頻出パターンを先に潰すのが最短です。
チェックポイント:
最初から完璧を目指すより、最低限の保険を積んで「壊れにくい運用」を作ります。
最低限チェック:
| 項目 | 目的 | 具体例 |
|---|---|---|
| 受信を軽くする | タイムアウト回避 | 受信→即200→キュー投入→非同期処理 |
| 冪等性（idempotency） | 重複を無害化 | event_id を保存して二重処理を防ぐ |
| 署名検証 | なりすまし防止 | HMAC署名をヘッダから検証（raw bodyで） |
| リプレイ対策 | 盗聴/再送の悪用を減らす | timestamp を検証し許容幅を決める |
| リトライ設計 | 一時障害に耐える | 5xx/429は再試行、4xxは失敗確定 |
| DLQ/再処理 | 復旧を速くする | 失敗イベントを隔離し、再処理できる状態にする |
| ログ/追跡ID | 調査を速くする | request_id と event_id を必ず記録 |
| アラート | 気づく速度を上げる | 失敗率/連続失敗/遅延で通知 |
| テスト送信 | 変更の安全性 | ステージングにテストイベントを送る |
Webhookの失敗は「本番のどこかで止まる」より「一部のイベントが欠ける」形で起きやすいです。受信（入口）と処理（重い処理）と通知（人間への連絡）を分離すると、復旧が簡単になります。
たとえば、受信側は「署名検証→即200→キューへ保存」までにし、キューのコンシューマが非同期で本処理を行う構成にします。自動化ツール側の再試行があっても、冪等性キーで二重処理を防げます。
署名検証が通らない原因の多くは「どの文字列に対して署名したか」がズレていることです。JSONとしてparseした結果ではなく、受信した“生のbody文字列（raw body）”が必要なケースが多いです。
最短の切り分けは、(1) raw body をそのままログに残す（本番はマスク/長さ制限）、(2) 署名対象文字列の仕様を確認する、(3) シークレットの取り違えを疑う、の順です。
代表例（ヘッダ名の一例）:
| 送信元 | 署名ヘッダ（例） | 注意点 |
|---|---|---|
| Stripe | Stripe-Signature | timestamp とペイロードで検証。許容時間幅を決める |
| GitHub | X-Hub-Signature-256 | sha256= の接頭辞に注意（raw bodyでHMAC） |
| Shopify | X-Shopify-Hmac-Sha256 | base64形式。raw bodyで計算し一致確認 |
チェックリスト:
Webhookは同じイベントが複数回届く前提で設計します。送信側の再試行、ネットワーク揺れ、受信側タイムアウト後の再送などで、重複は普通に起きます。
最小の冪等性は「イベントID（なければハッシュ）を保存して、既に処理済みならスキップする」ことです。DBがない場合でも、KVやキュー側のDedup機能など、どこかに“処理済み”を置く必要があります。
実装のコツ:
event_id があればそれをキーにするツール内で完結する場合でも、次の点で落ちがちです。
困ったときは、次の順で潰すと早いです。
1) 入口で必ずログが取れているか（受信の有無）
2) 同じ event_id が複数回届いていないか（冪等性の有無）
3) 受信処理が遅すぎないか（タイムアウト→再送の連鎖）
4) 署名検証の仕様に合っているか（raw body / timestamp）
Webhook連携が安定したら、次は「どの自動化に投資するか」を決める段階に進みます。L-001では、ツール比較と改善計測を同じ範囲でつなぎます。
入口で event_id と処理結果（成功/失敗、エラー種別）を必ずログに残し、失敗率や連続失敗で通知します。受信と処理を分離しておくと、入口は200のままでも再実行できます。
正常なケースが多いです（送信元の再試行、ネットワーク揺れ）。必ず冪等性を実装し、二重処理を無害化します。
署名対象が「生のbody文字列」か「解析後のJSON」かで失敗します。受信側でraw bodyを保持して検証し、ヘッダ名やシークレットの取り違えを確認します。
このループでは、記事を読んだ後に比較、テンプレ、改善レポートへ進める導線を増やしていきます。