支払いウェブフックドクター は何をしますか？
証拠から始め、再送信から始めないでください。壊れたハンドラーにイベントを再送すると、その副作用が繰り返される可能性があります。
一度に一つのタスクを進める
| 問題 | 参照先 |
|---|---|
| 署名失敗、シークレットの誤り、パース済みボディ、古い配信 | references/signatures.md |
| 二重クレジット、遅延処理、成功後の失敗、順序違いの返金 | references/reconciliation.md |
| 4xx/5xx/タイムアウト、復旧、イベント欠落、プロダクションロールアウト | references/incident-playbook.md |
| 検証済みプロトコルファクトとバージョン境界が必要 | references/sources.md |
| Stripe以外 / M-Pesaアダプタが必要 | references/provider-boundary.md |
ワークフロー
- スコープを確定する：プロバイダー、スナップショットかシンプルイベントか、テスト/ライブモード、コネクテッドアカウント、エンドポイントフレームワーク、APIバージョン。診断を変える不足している事実のみを質問する。
- ハンドラーコード、マイグレーション、期待される注文金額/通貨、サーバー作成のPaymentIntentマッピング、マスクされた配信メタデータを検査する。署名シークレットはローカル環境変数に保持する。ユーザーにシークレットや顧客ボディをチャットに貼り付けさせない。
- JSONをパースする前に、正確な生のリクエストバイトを検証する。デプロイ済みハンドラーには公式のStripe SDKを推奨する。バンドルされている依存関係のないベリファイアは、小さく検査可能な診断リファレンスであり、SDKの代替ではありません。
- 以下のローカルツールを使用して、まず合成フィクスチャで障害を再現する。証拠を「観測済み」「推測」「未検証」に分類する。有効な署名は配信を認証するものであり、注文が履行されるべきであることを証明するものではない。
- 最小の原因を修復し、回帰テストを追加する。支払いを信頼できるサーバーサイドの注文に結び付け、金額、通貨、アカウントスコープ、モードを比較する。受信ボックス、台帳更新、副作用インテントを一つのデータベーストランザクションにまとめる。
- 重複、同一オブジェクトに対する個別のイベント、再起動、順序違いの配信、失敗イベント、部分/全額返金を検証する。イベントタイムスタンプを全順序付けメカニズムとして使用しない。
- 調査結果、パッチ、テスト証拠、未解決の統合要件、明示的なロールバック/復旧計画を提出する。ユーザーの承認済みワークフローなしに、デプロイ、ライブイベントの再送信、返金の発行、送金を行わないこと。
ローカルツール
このスキルのルートから実行する：
npm test
npm run demo
文書化されたフィクスチャクロックを使用して、保存済みのテストモードフィクスチャを検査する：
export DOCTOR_FIXTURE_SECRET='fixture_only_not_a_live_secret'
node scripts/doctor.mjs --body fixtures/payment.json --header fixtures/signature.txt \
--secret-env DOCTOR_FIXTURE_SECRET --fixture-now 1794130000 \
--normalized-out /tmp/payment-doctor-event.json
python3 scripts/ledger.py --db /tmp/payment-doctor-reference.sqlite \
--orders fixtures/orders.json < /tmp/payment-doctor-event.json
エクスポートは既存のファイルへの上書きを拒否します。新しい出力パスを使用するか、意図的に自分自身の合成出力を削除してください。Python CLIは、明示的に指定されたローカルSQLiteデータベースのみに書き込みます。ベリファイアの信頼できる正規化出力を期待し、それ自体では署名を検証しません。決して公開ウェブフックエンドポイントとして公開しないでください。
通常の診断レポートには、顧客データ、生のペイロード、署名は含まれません。明示的な正規化エクスポートは、ローカルの調整に必要な識別子と整数金額を保持します。これをプライベートに保ち、バージョン管理から除外してください。
--fixture-now は古い合成テストイベント専用であり、ライブモードの入力を拒否します。通常の現在の配信では省略してください。参照台帳はライブモードのイベントを拒否し、Stripeを呼び出さず、アウトボックス行を送信しません。
必須レポート
- 結果: 何が起こったか、再現されたかどうか。
- 証拠: ファイル/行、サニタイズされた配信メタデータ、正確なコマンド、観測された結果。
- 根本原因: 確認された原因と残りの仮説。
- 修復: 最小限のパッチと、マイグレーション/バックフィルの影響。
- 回帰マトリックス: 重複、再起動、スコープ不一致、誤った金額/通貨、順序、返金のケース。
- 運用引き継ぎ: まだ必要なテストモード統合証拠、安全な再送信とロールバックの基準。
境界
サポートは意図的に狭い範囲です：Stripeのスナップショット payment_intent.succeeded、payment_intent.payment_failed、および返金オブジェクトイベント。シンプルイベント、サブスクリプション entitlements、Checkoutセッション、異議申し立て、マルチキャプチャ支払いセマンティクス、アプリケーション料金、税金、Connect転送には専用のアダプタが必要です。ゼロ件の結果は、セキュリティ認定や資金の到着の証明ではありません。拡張する前に参照を確認してください。