Webhookをローカルで再現するときは、過去payloadをそのまま本番handlerへ送る前に、入力・署名・受信・queue・業務副作用を分けます。HTTP 200が返ったことと、正しいeventを一度だけ処理したことは別です。架空fixtureと検証用接続を使い、どの層を試したかを記録します。
本稿はローカル再現の設計です。tunnel公開、Webhook転送、CLI実行、test event生成、署名検証、DB書込は行っていません。Stripeを製品例にしますが、他serviceへ同じ署名形式や再送条件を当てはめません。
目次
再現したい失敗を一つに絞る
受信できない、署名不一致、schema違い、重複、queue後の停止、外部Actionの結果不明を区別します。入口からすべてを再現しなくても、handlerの内部関数へfixtureを渡す試験で原因を絞れる場合があります。ただし、その試験でHTTP・署名・本物の配送まで確認済みとは報告しません。
表は横にスクロールできます
| 試験層 | 検証できること | 別に必要なこと |
|---|---|---|
| 内部関数とfixture | parse・条件・状態遷移 | 署名・配送 |
| local HTTP | method・path・body処理 | provider由来の証明 |
| 正規のtest配送 | provider/署名/受信経路 | 実業務の完了 |
| queue/worker | 再開・重複・副作用制御 | 入口での認証 |
endpoint、handler バージョン、event ID/type、schema/API バージョン、試験時刻、期待結果を固定します。取得した本番payloadを使う必要がある場合は、利用許可と個人情報・secretの扱いを確認します。まず架空fixtureで同じ構造や欠損を作れるかを検討します。
接続と副作用を検証用へ分ける
DB、queue、mail、CRM、決済等の接続先を確認します。localのアプリでも、本番credentialを読むと実dataへ作用し得ます。公開tunnelを作る場合は必要なendpointだけを対象にし、管理画面やdebug情報まで外へ見せない構成を用意します。
副作用はfakeや検証用resourceへ向け、送信先を許可されたテスト宛先へ限定します。入口で署名を検証する前に、debug目的で業務処理を走らせないようにします。記録には接続先の識別情報を残し、credential値やURL中のsecretは残しません。
正規のtest eventも、dataを作る場合がある
Stripe CLIのtrigger資料（新しいタブで開く）は、test event生成が実際のAPI要求を使い、必要なAPI objectを作成し、関連する別eventも起こし得ると説明しています。「testだから完全に副作用がない」と扱わず、対象account、sandbox/test mode、作られるobjectと配送先を確認します。
一つのevent typeを指定したのに複数eventが届いた場合も、即重複と判断しません。event IDとtype、対象object、作成順を見て、関連eventか同一eventの再送かを分けます。本番の再送操作と、架空eventを新たに作る操作を同じ復旧手順にしないようにします。
署名は元のbodyと、その経路のsecretで確認する
Stripeのendpoint管理資料（新しいタブで開く）は、raw body、署名header、endpoint secretの対応を案内しています。CLI転送用とdashboard管理endpointのsecretは別なので、prefixが同じという理由で混ぜません。秘密値をprintしてticketへ貼る方法を使わず、設定元と対象endpointを確認します。
署名済みbodyをJSON parseして整形し直すと、検証対象のbytesが変わる場合があります。HTTP入口のmiddleware順序とraw bodyの取得を確認します。payloadを匿名化したfixtureは、そのまま元の署名に一致するとは限りません。内部ロジック試験用のfixtureと、正規配送の署名試験を別にします。
再送・並行・途中停止を条件にする
通常の一回だけでなく、同じeventの再送、ほぼ同時の重複、queue後の停止、外部処理後に完了記録を失う場合を設計します。再送時に新しいIDを作ると、同一eventの重複排除を試したことになりません。状態を消してから同じeventを送る試験も、通常の再送とは区別します。
表は横にスクロールできます
| 条件 | 観察するもの | 合格の方向 |
|---|---|---|
| 署名不正 | 業務Action数 | 処理しない |
| 同一eventの順次再送 | 保存状態と副作用 | 必要な処理は一度 |
| 同一eventの並行受信 | claimと一意性 | 二者が同時に処理しない |
| queue後に停止 | 再開位置 | 未処理が落ちない |
| 外部応答を喪失 | 照会と状態 | 不明を無条件再送しない |
ACK、queueへの受入、worker完了、下流結果を別に観測します。200だけを成功指標にすると、受入後に落ちた業務処理を見逃します。失敗pageやeventをAIへ推測補完させず、固定fixtureと状態遷移の差分を読みます。
再現結果と、試していない境界を残す
終了時には、endpointと転送設定、生成したtest object、queue、fixture、検証用secretの運用上の扱いを確認します。tunnelやlistenerを残す必要がなければ停止する手順を用意し、本番の再送・共有設定を変更していないかを見ます。今回それらの操作を実施したという意味ではありません。
完了記録には、再現した失敗、使った入力バージョン、署名/配送を含めた範囲、状態と副作用数、修正差分、未確認の本番条件を残します。ローカル試験は原因を絞る証拠であり、本番配送や実顧客処理の成功へそのまま一般化しないようにします。