Webhook

Event types

eventType	Description
`PAYMENT_NOTIFICATION`	Payment completed or failed
`REFUND_NOTIFICATION`	Refund completed or failed
`TOKENIZATION_NOTIFICATION`	Token generated, token status changed, or card information updated
`SUBSCRIPTION_STATUS_NOTIFICATION`	Subscription status change (activation, cancellation, etc.; also used for subscription billing events)
`SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION`	Subscription period change
`SUBSCRIPTION_CHANGE_NOTIFICATION`	Subscription change (upgrade/downgrade) completed

Common structure

All Webhooks use the same request structure:

POST {notifyUrl}
Content-Type: application/json
X-SIGNATURE: {Waffo private-key signature}

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.

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.

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 status changes (including activation, cancellation, billing results, etc.). 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 when the subscription period reaches a terminal state, used to track renewal results. 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, and the response body must be {"message":"success"}, and must include the X-SIGNATURE response header (sign the response body using the merchant private key).

Waffo validates both the HTTP status code and the response body. If the response format is incorrect or the signature is missing, Waffo will treat the delivery as failed and retry.

Using the SDK (recommended)

The SDK’s handleWebhook() method automatically performs signature verification, event routing, and response signing:

const result = await waffo.webhook().handleWebhook(body, signature);
res.setHeader('X-SIGNATURE', result.responseSignature);
res.status(200).send(result.responseBody);

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.

Event	When it fires	Best for
`SUBSCRIPTION_STATUS_NOTIFICATION`	Subscription master status changes (activation, cancellation, closure)	Managing the subscription lifecycle: granting or revoking user entitlements
`SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION`	Terminal state of each renewal period (no notifications during retries — only the final outcome)	Tracking the final result of each billing period without caring about intermediate retry attempts
`PAYMENT_NOTIFICATION`	Every payment attempt (first period + every retry of subsequent periods)	Getting detailed failure reasons, payment timestamps, and other per-attempt details

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

Getting Started

Core Concepts

Integration

SDK

Tools & Reference

Webhook - event type list

Event types

Common structure

PAYMENT_NOTIFICATION

REFUND_NOTIFICATION

TOKENIZATION_NOTIFICATION

SUBSCRIPTION_STATUS_NOTIFICATION

SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION

SUBSCRIPTION_CHANGE_NOTIFICATION

Merchant response

Using the SDK (recommended)

Manual response

Subscription notification selection guide

​Event types

​Common structure

​PAYMENT_NOTIFICATION

​REFUND_NOTIFICATION

​TOKENIZATION_NOTIFICATION

​SUBSCRIPTION_STATUS_NOTIFICATION

​SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION

​SUBSCRIPTION_CHANGE_NOTIFICATION

​Merchant response

​Using the SDK (recommended)

​Manual response

​Subscription notification selection guide

Event types

Common structure

PAYMENT_NOTIFICATION

REFUND_NOTIFICATION

TOKENIZATION_NOTIFICATION

SUBSCRIPTION_STATUS_NOTIFICATION

SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION

SUBSCRIPTION_CHANGE_NOTIFICATION

Merchant response

Using the SDK (recommended)

Manual response

Subscription notification selection guide