> ## 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                                                                             |
| `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 after the payment is completed.

```json theme={null}
{
  "eventType": "PAYMENT_NOTIFICATION",
  "acquiringOrderId": "ACQ123456",
  "merchantOrderId": "ORDER123",
  "paymentRequestId": "REQ123",
  "orderStatus": "PAY_SUCCESS",
  "orderAmount": "100.00",
  "orderCurrency": "USD",
  "finalDealAmount": "100.00"
}
```

## REFUND\_NOTIFICATION

Sent after the refund is completed, and delivered to the `refundNotifyUrl` specified when creating the refund.

```json theme={null}
{
  "eventType": "REFUND_NOTIFICATION",
  "acquiringRefundOrderId": "REF123456",
  "refundRequestId": "REFUND_REQ123",
  "refundStatus": "ORDER_FULLY_REFUNDED",
  "refundAmount": "100.00"
}
```

## 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](/en/developer-docs/integration/tokenization/generate).

```json theme={null}
{
  "eventType": "TOKENIZATION_NOTIFICATION",
  "result": {
    "tokenRequestId": "202510111010050001",
    "tokenId": "tok_xxxxxxxxxxxx",
    "tokenType": "CARD",
    "tokenStatus": "UNVERIFIED",
    "tokenData": {
      "maskedCardInfo": "481852******0147",
      "cardHolderName": "Zhang san",
      "cardExpiry": "01/2030",
      "cardBin": "481852",
      "cardScheme": "VISA",
      "cardType": "CREDIT_CARD",
      "cardIssuerName": "INTL HDQTRS-CENTER OWNED",
      "cardIssueCountryCode": "RUS"
    },
    "billingAddress": {
      "countryCode": "USA",
      "region": "CA",
      "city": "Cupertino",
      "postalCode": "95014",
      "address": "One Apple Park Way"
    },
    "merchantUserId": "merchant-user-001",
    "merchantInfo": {
      "merchantId": "your_merchant_id",
      "subMerchantId": ""
    }
  }
}
```

| Field            | Description                                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `tokenRequestId` | Request ID passed by the merchant when starting tokenization. This field may be absent when the status change is triggered by Waffo |
| `tokenId`        | Token ID. Store it securely and use it for later token payments                                                                     |
| `tokenType`      | Token type. Currently `CARD`                                                                                                        |
| `tokenStatus`    | Token status: `UNVERIFIED`, `VERIFIED`, `EXPIRED`, or `SUSPENDED`                                                                   |
| `tokenData`      | Card summary, including masked card number, expiry, BIN, card scheme, card type, issuer, and issuing country                        |
| `billingAddress` | Cardholder billing address                                                                                                          |
| `merchantUserId` | Merchant-side user ID                                                                                                               |
| `merchantInfo`   | Merchant information                                                                                                                |

## SUBSCRIPTION\_STATUS\_NOTIFICATION

Sent when the subscription status changes (including activation, cancellation, billing results, etc.).

```json theme={null}
{
  "eventType": "SUBSCRIPTION_STATUS_NOTIFICATION",
  "subscriptionId": "SUB123456",
  "subscriptionStatus": "ACTIVE"
}
```

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.

```json theme={null}
{
  "eventType": "SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION",
  "subscriptionId": "SUB123456",
  "period": "3",
  "orderStatus": "PAY_SUCCESS"
}
```

## SUBSCRIPTION\_CHANGE\_NOTIFICATION

Sent when a subscription change (upgrade/downgrade) is completed.

```json theme={null}
{
  "eventType": "SUBSCRIPTION_CHANGE_NOTIFICATION",
  "result": {
    "subscriptionRequest": "new-sub-req-001",
    "originSubscriptionRequest": "orig-sub-req-001",
    "subscriptionId": "waffo-sub-12345",
    "subscriptionChangeStatus": "SUCCESS",
    "subscriptionAction": "UPGRADE",
    "remainingAmount": "50.00",
    "currency": "HKD"
  }
}
```

| subscriptionChangeStatus | Description            |
| ------------------------ | ---------------------- |
| `SUCCESS`                | Change succeeded       |
| `CLOSED`                 | Change failed / closed |

## 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).

<Warning>
  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.
</Warning>

### Using the SDK (recommended)

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

```typescript theme={null}
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](/en/developer-docs/webhook/retry) for details.

***

## Subscription notification selection guide

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

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