Webhook冪等性：Stripeが同じコミッションイベントを3回送信する時

14ヶ月にわたりthMenuの全Stripe webhookをログした: 100,000イベント中312個が同じevent_idで2~3回届いた。Stripeの"at-least-once delivery"約束の具体的な数字 — 冪等性なしでは、コミッション台帳に3件の重複行。

同じイベントが3回届く理由

Stripeが約10秒以内に2xx応答を受信しない場合、リトライする。TCPタイムアウト、lambdaコールドスタート、一時的DNS障害、成功処理後の応答書き込み前接続断 — すべてリトライをトリガーする。

3つの頻出シナリオ: Cloudflare Workersコールドスタート10秒超過、D1バッチトランザクションがコミットされたが接続断、Stripeダッシュボードで手動"resend"クリック。

INSERT-Claimパターン

thMenuの防御はstripe_webhook_eventsテーブル、event_id PRIMARY KEY。最初のアクション: INSERT。Unique制約エラー23505 = 重複 — 200 OK no-op。

重要: claimはビジネスロジックの前でなければならない。さもなくばレースコンディション。

レースコンディション: 順序外イベント

実際の本番インシデント: customer.subscription.updatedがcheckout.session.completedより800ms先に到達。UPDATEは0行影響。修正: claimをロールバック、503返却、Stripeがリトライ。

FAQ

署名検証はclaim前か後か？前。Verifyは安く、DB書き込みは高い。

冪等テーブルの保持期間は？Stripeは30日リトライを保証；我々は90日保持。

Stripeは永遠にリトライするか？いいえ、最大3日。

お役に立ちましたか?シェアしてください。