Webhook 概要

Jammがサーバーにリアルタイムでイベント通知を配信する仕組み、エンドポイントの要件、URLの登録方法について説明します。

Webhookは、決済の成功、返金の完了、契約の有効化など、連携内でイベントが発生したときにJammがサーバーへ送信するリアルタイムのHTTP通知です。ポーリングなしでシステムを同期させるために使用します。

Webhookの仕組み

該当するイベントが発生すると、Jammはオンボーディング時に登録されたURLにPOSTリクエストを送信します。ボディは以下を含むJSONドキュメントです：

• id — 一意のWebhook ID（mwh-*）。再試行時も同じ値が送信されます。
• signature — contentフィールドのHMAC-SHA256。sha256=<hex>形式（Signature Verificationを参照）。
• event_type — 発生したイベント（Event Referenceを参照）。
• content — イベント固有のペイロード。
• created_at — イベントのタイムスタンプ。

エンドポイントの要件

Webhookエンドポイントは以下を満たす必要があります：

• HTTPSで外部から到達可能であること。
• Content-Type: application/jsonのPOSTリクエストを受け付けること。
• 正常に受信したことの確認として2xxステータスコードを返すこと。
• ペイロードを信頼する前に署名を検証すること（Signature Verificationを参照）。

⏱️ タイムアウトについて: Jammは1回の配信試行あたり最大2分を許容します。エンドポイントが時間内に応答しない場合、その試行は失敗とみなされ再試行されます（Retries & Idempotencyを参照）。

URLの登録とテスト

URLの登録

Webhook URLはオンボーディング時に登録します。環境ごとに1 URLを推奨します — ステージングと本番のWebhookは独立して配信されます。オンボーディング後にWebhook URLを変更する場合は、Jammの担当者にご連絡ください。

テスト

ステージングと本番は完全に分離されているため、実際の資金移動を伴わずにステージングでWebhookハンドラーを検証できます。

ベストプラクティス

• 署名を検証する — イベントを信頼する前に必ず検証（Signature Verificationを参照）。
• 速やかに確認応答する — イベントを永続化したらすぐに2xxを返し、重い処理は非同期で行う。
• 重複排除する — Webhookのidで重複を排除。同じイベントが複数回届くことがあります。
• 再試行 vs アラート — 2xx以外は一時的な失敗のときだけ返す（Jammが再送）。恒久的な失敗（不明なID、不正なデータ）では2xxを返して内部でアラートを出す。
• 配信だけに依存しない — GetCustomer / GetChargeなどのエンドポイントを呼び出して重要な状態の整合を取る。

完全な再試行ポリシー、応答ガイダンス、整合の方法はRetries & Idempotencyを参照してください。

メッセージの再送インターバル

Webhookメッセージを受信するサーバーが4xx、5xxのHTTPステータスコードを返すと、メッセージは一定間隔後に最大20回再送されます。

• 1時間後
• 2時間後
• 3時間後（以降、3時間ごとに送信されます）