Webhook — 概要

Webhook は 信頼できる シグナルです。ブラウザのコールバック (onSuccess) やダッシュボードの表示は補助的な情報であり、 Webhook が真実のソースです。

配信保証

• 少なくとも 1 回。 サーバーがタイムアウト内に 2xx を返さない場合、 1 つのイベントは最大 6 回 配信される可能性があります。 ハンドラは冪等にしてください — X-Delivery で重複排除を行います。
• HTTP リクエストごとに 1 イベント。 バッチ配信は行いません。
• エンドポイント単位の独立性。 複数のエンドポイントを登録している場合、 それぞれが独立した配信とリトライのトラックを持ちます。 あるマーチャント URL が遅くても他に影響しません — ホストごとに サーキットブレーカが付いています。
• 署名付き。 すべてのペイロードに X-Signature ヘッダーが付きます (シークレットローテーション後の 24 時間ウィンドウ中は X-Signature-Prev も付きます)。本文を扱う前に必ず検証してください。 詳しくは 署名検証 をご覧ください。

サブスクライブ可能なイベント種別

ダッシュボードはこのリストを GET /v1/webhooks/event-types から取得するため、 エンドポイントの作成・編集フォームはプラットフォームが実際に発行する イベントと常に一致します。発行されないイベントへのサブスクライブは 作成時に明確なエラーで拒否されます。

ペイロード + ヘッダー

HTTP ボディはイベント固有のデータオブジェクトそのものです。 Stripe スタイル の外側エンベロープはありません — イベント種別、配信 ID、発行タイムスタンプ などのフィールドは代わりに ヘッダー に入ります。payment.settled の ボディは次のような形です:

{
  "receipt_id":        "rcp_…",
  "order_id":          "ord_…",
  "payment_intent_id": "pin_…",
  "checkout_session_id": "cst_…",
  "merchant_id":       "mer_…",
  "customer_id":       "cus_…",
  "total":             "49.00",
  "currency":          "USD",
  "payment_method":    "crypto",
  "token":             "USDC",
  "network":           "polygon",
  "tx_hash":           "0x…",
  "deposit_address":   "0x…",
  "treasury_address":  "0x…",
  "amount_received":   "49.00",
  "confirmations":     5,
  "metadata":          { /* per-event */ }
}

他のイベントは独自のフィールドセットを持ちます — イベント単位のドキュメントが 揃うまでは、正式な形は payment-service/internal/domain/events.go のパブリッシャ 構造体を参照してください。フィールド名は安定 (lower snake_case); オンチェーン tx ハッシュは常に tx_hash (not transaction_hash) です。

受信リクエストのヘッダー

Content-Type:      application/json
X-Event:           payment.settled
X-Delivery:        7c9e6679-7425-40de-944b-e07fc1f90ae7
Idempotency-Key:   7c9e6679-7425-40de-944b-e07fc1f90ae7
X-Timestamp:       1729536000
X-Signature:       sha256=9a8b7c…
X-Signature-Prev:  sha256=fa31b2…    (ローテーション猶予ウィンドウ中のみ)

リトライスケジュール

エンドポイントがタイムアウト内に 2xx を返さない場合、 次のスケジュールでリトライします (初回試行からの相対時刻):

試行 6 が失敗すると配信は デッドレター に移され、マーチャント アカウントのメール宛に通知されます。デッドレター入りしたイベントは ダッシュボードの Developers → Webhooks → Delivery history パネル、 または直接 POST /v1/webhooks/deliveries/:id/replay でリプレイできます。 各リプレイは独自の X-Delivery を持つ新しい配信行を作成します — 監査 チェーンは parent_delivery_id で元に紐付くため、リプレイのリトライが 元のイベントを隠すことはありません。

エンドポイントの登録

マーチャントダッシュボード  から:

1. Developers → Webhooks → + Add endpoint
2. URL を貼り付け — https://… のみ (プレーン HTTP は拒否されます; 作成フォームは localhost、プライベート IP レンジ、ユーザー情報を 含む URL もブロックします)
3. サブスクライブするイベントを選択 (全イベントは *)
4. 環境を選択 — test または live (それぞれ独自のシークレットを 持ち、互いに混在することはありません)
5. 保存 → ダッシュボードが署名シークレット (whsec_…) を 1 度だけ 表示します。 サーバー側に保存してください; 次の 2 つの機能で使います。

マーチャントごと、環境ごとに最大 10 個 のエンドポイントを登録できます (例: 本番フルフィルメント用、ステージングミラー用、Slack 通知用)。 それぞれが独立したリトライ状態、シークレット、ホスト単位のサーキット ブレーカを維持します。

各エンドポイントのライフサイクル操作

各エンドポイントカードの ⋮ メニューには以下が並びます:

• Edit — URL、説明、サブスクリプションリストを変更します。 新しい URL は作成時と同じ https:///SSRF ルールで再検証されます。
• Send Test — webhook.test.ping エンベロープを現在のシークレットで 署名して同期 POST します。ダッシュボードに HTTP ステータス、レイテンシ、 応答の先頭 512 バイトが表示されます。RMQ パイプラインをバイパスするので 結果は即座に返ります。
• Rotate Secret — 新しいシークレットを生成します。前のシークレットは 24 時間 有効のままです (この間、配信は X-Signature と X-Signature-Prev の両方を含むので、検証側がどちらの鍵を使っていても 再デプロイ中もイベントを受け入れ続けられます)。
• Reveal Secret — 既存のシークレットを再表示します。新規の 2FA 検証で ゲートされ、監査ログに記録されます; コピーを紛失し、かつローテーションが 許容できない場合のみ使用してください。
• Enable / Disable — 配信履歴を失わずに is_active をトグルします。 無効化されたエンドポイントはダッシュボードに残りますが、新しい配信は 受け取りません。
• Delete — 永続的に削除します。後で再有効化する可能性があるなら Disable を使ってください。

ハンドラのコツ

1. 2xx をすばやく返す。 重い処理の前に 200 OK で確認応答 — フルフィル メントはバックグラウンドキューにキックしてください。試行ごとの タイムアウトは 10 秒 で、それより長く応答を保持するとリトライが トリガーされます。タイムアウトはプラットフォーム側で固定で、マーチャント 設定では変更できません — ハンドラがどうしてもより長い時間を必要とする 場合はサポートに連絡してください。
2. X-Delivery で重複排除する (または Idempotency-Key — 同じ値)。 2xx を返しても上流プロキシが接続を切ってリトライがトリガーされる可能性が あります; 配信 ID は同じ配信行のすべてのリトライにわたって安定なので、 これが正しいキーです。
3. 未知のイベント種別を許容する。 新しいイベントが現れる可能性があります; 4xx ではなく 200 + no-op を返してください。さもないとリトライキューが 膨らみます。
4. ビジネスロジックの横に X-Delivery をログする。 何か起きたとき、 それが我々の側と御社の側を結合するキーです。

次に

• 署名検証 — 正確なアルゴリズム + リプレイ対策パターン。
• コンセプト → セッション — 各イベント発火時に セッションがどの状態にあるか。