イベントタイプ
共通構造
すべての Webhook は同じリクエスト構造を使用します。
PAYMENT_NOTIFICATION
決済が完了または失敗したときに送信されます。
通知本文の eventType は常に PAYMENT_NOTIFICATION です。result の構造は、Order Inquiry のレスポンスに含まれる data と同一です。完全なレスポンス構造は API リファレンスを参照してください。
REFUND_NOTIFICATION
返金完了後に送信され、返金作成時に指定した refundNotifyUrl に配信されます。
通知本文の eventType は常に REFUND_NOTIFICATION です。result の構造は、Refund Inquiry のレスポンスに含まれる data と同一です。完全なレスポンス構造は API リファレンスを参照してください。
TOKENIZATION_NOTIFICATION
Tokenization の完了、Token ステータスの変更、または Token のカード情報が更新されたときに送信されます。Waffo は Generate token の呼び出し時に渡された notifyUrl にこの通知を送信します。
通知本文の eventType は常に TOKENIZATION_NOTIFICATION です。result の構造は、Token Inquiry のレスポンスに含まれる data 配列の 1 オブジェクトと同一です。完全なレスポンス構造は API リファレンスを参照してください。
result.tokenId を冪等性キーとして通知を処理し、各通知の最新値でローカルの tokenStatus と Token データを更新してください。
SUBSCRIPTION_STATUS_NOTIFICATION
サブスクリプションのステータスが変化したとき (アクティベーション、キャンセル、課金結果などを含む) に送信されます。
通知本文の eventType は常に SUBSCRIPTION_STATUS_NOTIFICATION です。result の構造は、Subscription Inquiry のレスポンスに含まれる data と同一です。完全なレスポンス構造は API リファレンスを参照してください。
SDK では 2 つのハンドラーが提供されています。
onSubscriptionStatus() — このイベントを直接処理しますonSubscriptionPayment() — onSubscriptionStatus が登録されていない場合のフォールバック処理
SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION
サブスクリプションの期間が終局状態に達したときに送信され、更新 (継続課金) 結果の追跡に使用します。
通知本文の eventType は常に SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION です。result の構造は、Subscription Inquiry のレスポンスに含まれる data と同一です。完全なレスポンス構造は API リファレンスを参照してください。
SUBSCRIPTION_CHANGE_NOTIFICATION
サブスクリプション変更 (アップグレード/ダウングレード) が完了したときに送信されます。
通知本文の eventType は常に SUBSCRIPTION_CHANGE_NOTIFICATION です。result の構造は、Subscription Change Inquiry のレスポンスに含まれる data と同一です。完全なレスポンス構造は API リファレンスを参照してください。
加盟店の応答
すべての Webhook に対して HTTP 200 を返し、応答ボディを {"message":"success"} にする必要があります。
Waffo は HTTP ステータスコードと応答ボディの両方を確認します。応答フォーマットが不正な場合、Waffo は配信失敗として扱い再送します。
SDK を使用する (推奨)
SDK の handleWebhook() メソッドは、署名検証、イベントルーティング、応答ボディの構築を自動的に実行します。
手動応答
SDK を使わない場合、応答ボディは以下のいずれかである必要があります。
{"message":"success"} — 処理成功{"message":"failed"} — 処理失敗。Waffo は再送します{"message":"unknown"} — ステータス不明。Waffo は再送します
再送ポリシー: failed または unknown を返した場合、Waffo は最大 8 回 (初回を含む) 再送します。間隔は 30 秒から 8 時間まで徐々に長くなります。詳細は再送と障害復旧をご覧ください。
サブスクリプション通知の選択ガイド
サブスクリプションのシナリオでは 3 種類の通知が関係します。必要なものをサブスクライブしてください。
SUBSCRIPTION_STATUS_NOTIFICATION と SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION は非同期で配信される Webhook で、キュー消費・再送・ネットワーク遅延などの影響により受信順序は保証されません。受信順序をビジネス状態管理の根拠にしないでください。正しい処理方法（冪等な重複排除、いずれかのコールバック受信後に subscription/inquiry で最終状態を確認）は 処理のベストプラクティス を参照してください。推奨する組み合わせ:
- 最小限の連携:
SUBSCRIPTION_STATUS_NOTIFICATION + SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION をサブスクライブ
- フル連携: すべて 3 種類をサブスクライブ。
PAYMENT_NOTIFICATION を使って再試行ごとの詳細な失敗理由を取得します
