Skip to main content

​
イベントタイプ

​
共通構造

すべての Webhook は同じリクエスト構造を使用します。

​
PAYMENT_NOTIFICATION

決済が完了または失敗したときに送信されます。 通知本文の eventType は常に PAYMENT_NOTIFICATION です。result の構造は、Order Inquiry のレスポンスに含まれる data と同一です。完全なレスポンス構造は API リファレンスを参照してください。

​
Subscription の決済イベント

Subscription の決済では、result.subscriptionInfo.subscriptionEvent で通知の対象となる処理を判別してください。 これらは subscriptionEvent の値であり、通知の eventType は PAYMENT_NOTIFICATION のままです。
期間ごとの利用権付与：SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION を起点に利用権付与前の確認を行うことを推奨します。署名を検証し、Subscription、期間、当該期間の請求額、最終的な決済成功を確認してから、subscriptionId と期間をキーとして冪等に対応する利用権を付与してください。PAYMENT_NOTIFICATION の受信や subscriptionEvent の値だけを根拠に利用権を付与しないでください。USER_ADD_PAYMENT_METHOD と TOPUP_CHARGE はそれぞれ個別に処理し、新しい期間の課金や利用権付与の根拠として扱わないでください。詳細は Subscription の利用権付与を参照してください。

​
REFUND_NOTIFICATION

返金完了後に送信され、返金作成時に指定した refundNotifyUrl に配信されます。 通知本文の eventType は常に REFUND_NOTIFICATION です。result の構造は、Refund Inquiry のレスポンスに含まれる data と同一です。完全なレスポンス構造は API リファレンスを参照してください。

​
CHARGEBACK_NOTIFICATION

Chargeback が作成されたとき、またはステータスが変更されたときに送信されます。Waffo は Portal で設定された chargebackNotifyUrl に通知を配信します。 通知本文の eventType は常に CHARGEBACK_NOTIFICATION です。result の構造は、Chargeback Inquiry のレスポンスに含まれる data と同一です。最新の通知に含まれる chargebackStatus を正として扱ってください。

​
WITHDRAW_NOTIFICATION

加盟店が /api/v1/withdraw/create で作成した出金が成功または失敗したときに送信されます。Waffo は、そのリクエストの notifyUrl（必須）に通知を配信します。 通知本文の eventType は常に WITHDRAW_NOTIFICATION です。result の構造は /api/v1/withdraw/inquiry のレスポンスと同じです。エンドポイントとステータスについては出金・残高 API を参照してください。 通知を受け取ったら、署名を検証してから /api/v1/withdraw/inquiry で最新のステータスを照会し、照会結果を正として扱ってください。加盟店のレスポンス形式は本ページの加盟店の応答を、再送ルールは再送と障害復旧を参照してください。

​
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

Subscription 本体のステータスが変化したとき（有効化、キャンセル、クローズ）に送信されます。 通知本文の eventType は常に SUBSCRIPTION_STATUS_NOTIFICATION です。result の構造は、Subscription Inquiry のレスポンスに含まれる data と同一です。完全なレスポンス構造は API リファレンスを参照してください。 SDK では 2 つのハンドラーが提供されています。
  • onSubscriptionStatus() — このイベントを直接処理します
  • onSubscriptionPayment() — onSubscriptionStatus が登録されていない場合のフォールバック処理

​
SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION

Subscription の期間ごとの最終決済結果（第 2 期、第 3 期の更新結果など）を通知します。再試行中は通知せず、その期間の最終結果だけを通知します。個々の再試行ではなく、各期間の最終結果を確認する場合に受信してください。 通知本文の 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 を使って再試行ごとの詳細な失敗理由を取得します
利用権の付与前の確認と冪等性については、Subscription の利用権付与を参照してください。