> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook - event type list

> Detailed descriptions and payload examples for all Waffo Webhook event types.

## Event types

| eventType | Description |
| - | - |
| `PAYMENT_NOTIFICATION` | Payment completed or failed |
| `REFUND_NOTIFICATION` | Refund completed or failed |
| `CHARGEBACK_NOTIFICATION` | Chargeback created or status changed |
| `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](/docs/api-reference/order-inquiry/order-inquiry.md). 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](/docs/api-reference/refund-inquiry/refund-inquiry.md). 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](/docs/api-reference/chargeback-inquiry/chargeback-inquiry.md). 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](/docs/api-reference/waffo-tokenization-api/tokenization-generate.md).

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](/docs/api-reference/waffo-tokenization-api/tokenization-inquiry.md). 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](/docs/api-reference/subscription-inquiry/subscription-inquiry.md). 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](/docs/api-reference/subscription-inquiry/subscription-inquiry.md). 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](/docs/api-reference/subscription-change-inquiry/subscription-change-inquiry.md). 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"}`.

> [!WARNING]
>
> 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.

### Using the SDK (recommended)

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

```typescript theme={null}
const result = await waffo.webhook().handleWebhook(body, signature);
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](/docs/en/developer-docs/webhook/retry.md) for details.

***

## Subscription notification selection guide

Subscription scenarios involve three types of notifications. Subscribe to the ones you need:

> [!WARNING]
>
> `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](/docs/en/developer-docs/webhook/best-practices.md).

| 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 |

> [!TIP]
>
> **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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.