Stripe webhook の信頼性土台(inbox 方式・冪等・取りこぼし突合)を決める

[reiroop]

背景

#17 は Stripe webhook(invoice-paid)の実装 issue だが、その土台となる信頼性の設計方針が未確定。Stripe のイベントは仕様上、重複・順序不定・遅延・配信失敗が必ず起きる。

なぜ今決めるか

冪等・取りこぼし耐性を後から付けると、二重計上や記録欠損が既に台帳に生じた後になり、どの入金が欠けたかを判定する根拠が残らない。webhook を入金記録の唯一の入力にすると、配信保証が無いぶん恒久的な穴が生じる。この土台を #17 実装前に決める必要がある。

論点・選択肢

• inbox 方式: 受信イベントを Stripe event id の一意制約付きでまず永続化し、その上で状態更新を同一トランザクション内で行う。処理済みフラグと状態更新を束ねて exactly-once に近づける。
• 順序不定への耐性: イベント種別ではなく対象オブジェクトの現在状態を Stripe で確認して収束させるか、created で新旧を判定するか。
• 「入金の真実は webhook イベントであり、同期レスポンスやブラウザのリダイレクト完了ではない」を原則として固定する(会員化・台帳確定の書き込みは webhook のみを起点にする)。
• 取りこぼし対策: 配信は保証されない前提で、Stripe を入金イベントの上流の真実として突合し、欠損を埋める定期リコンサイル/バックフィル経路を土台として設計する(実行基盤は非同期処理基盤の決定に依存)。

受け入れ条件

• イベント受信テーブルの存在・トランザクション境界・購読イベント型・突合方針が決まり、Stripe webhook(invoice-paid)を実装する #17 の実装前提として文書化されている。

関連

#17(webhook 実装)の土台(親)。お金の記録アーキテクチャ、非同期・定期処理基盤の決定に依存/接続する。