Skip to main content

​
Event types

​
Common structure

All Webhooks use the same request structure:

​
PAYMENT_NOTIFICATION

Sent when the payment completes or fails. The notification body always uses PAYMENT_NOTIFICATION as its eventType. The result structure is identical to the data returned by Order Inquiry. Refer to the API Reference for the complete response structure.

​
Subscription payment events

For Subscription payments, use result.subscriptionInfo.subscriptionEvent to identify the business purpose of the payment notification: These are values of subscriptionEvent; the notification’s eventType remains PAYMENT_NOTIFICATION.
Granting period entitlements: We recommend using SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION to trigger period entitlement checks. Verify the signature and check the Subscription, period, amount due for that period, and final successful payment result before granting the corresponding entitlements idempotently by subscriptionId and period. Do not grant entitlements solely because you received PAYMENT_NOTIFICATION or based only on the value of subscriptionEvent.Handle USER_ADD_PAYMENT_METHOD and TOPUP_CHARGE separately. Do not treat them as charges for a new period or as the basis for granting a new period’s entitlements. See Grant Subscription entitlements for the full guidance.

​
REFUND_NOTIFICATION

Sent after the refund is completed, and delivered to the refundNotifyUrl specified when creating the refund. The notification body always uses REFUND_NOTIFICATION as its eventType. The result structure is identical to the data returned by Refund Inquiry. Refer to the API Reference for the complete response structure.

​
CHARGEBACK_NOTIFICATION

Sent when a Chargeback is created or its status changes. Waffo delivers the notification to the chargebackNotifyUrl configured in the Portal. The notification body always uses CHARGEBACK_NOTIFICATION as its eventType. The result structure is identical to the data returned by Chargeback Inquiry. Treat the chargebackStatus in the latest notification as authoritative.

​
TOKENIZATION_NOTIFICATION

Sent when tokenization is completed, the token status changes, or token card information is updated. Waffo sends this notification to the notifyUrl passed when calling Generate token. The notification body always uses TOKENIZATION_NOTIFICATION as its eventType. The result structure is identical to one object in the data array returned by Token Inquiry. Refer to the API Reference for the complete response structure. Process notifications idempotently using result.tokenId, and update the locally stored tokenStatus and Token data with the latest values from each notification.

​
SUBSCRIPTION_STATUS_NOTIFICATION

Sent when the Subscription master status changes (activation, cancellation, closure). The notification body always uses SUBSCRIPTION_STATUS_NOTIFICATION as its eventType. The result structure is identical to the data returned by Subscription Inquiry. Refer to the API Reference for the complete response structure. The SDK provides two handlers:
  • onSubscriptionStatus() — handle this event directly
  • onSubscriptionPayment() — fallback handling when onSubscriptionStatus is not registered

​
SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION

Sent with the final payment result for a Subscription period, such as a renewal in the second or third period. No notifications are sent during retries; only the final result for the period is sent. Subscribe to this event when you need each period’s final outcome without tracking individual retry attempts. The notification body always uses SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION as its eventType. The result structure is identical to the data returned by Subscription Inquiry. Refer to the API Reference for the complete response structure.

​
SUBSCRIPTION_CHANGE_NOTIFICATION

Sent when a subscription change (upgrade/downgrade) is completed. The notification body always uses SUBSCRIPTION_CHANGE_NOTIFICATION as its eventType. The result structure is identical to the data returned by Subscription Change Inquiry. Refer to the API Reference for the complete response structure.

​
Merchant response

All Webhooks must return HTTP 200 with a response body of {"message":"success"}.
Waffo checks both the HTTP status code and the response body. If the response format is incorrect, Waffo treats the delivery as failed and retries.
The SDK’s handleWebhook() method automatically performs signature verification, event routing, and response body construction:

​
Manual response

If you are not using the SDK, the response body must be one of the following:
  • {"message":"success"} — processed successfully
  • {"message":"failed"} — processing failed; Waffo will retry
  • {"message":"unknown"} — status unknown; Waffo will retry
Retry policy: When failed or unknown is returned, Waffo will retry up to 8 times (including the initial attempt), with intervals increasing from 30 seconds to 8 hours. See Retries and failure recovery for details.

​
Subscription notification selection guide

Subscription scenarios involve three types of notifications. Subscribe to the ones you need:
SUBSCRIPTION_STATUS_NOTIFICATION and SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION are delivered asynchronously; queue consumption, retries, and network latency mean the delivery order is not guaranteed. Do not use delivery order as the source of truth for your business state machine. For the correct handling approach (idempotent dedup, and calling subscription/inquiry after either callback to get the final state), see Handling best practices.
Recommended combinations:
  • Minimal integration: Subscribe to SUBSCRIPTION_STATUS_NOTIFICATION + SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION
  • Full integration: Subscribe to all three — use PAYMENT_NOTIFICATION to capture detailed failure reasons for every retry attempt
For entitlement checks and idempotency, see Grant Subscription entitlements.