Webhook

W Checkout Webhook is used to push events such as order/refund/settlement/abnormal payment to merchants, facilitating real-time business status updates and reconciliation in the client system.

1. Server Preparation

Please implement a publicly accessible Webhook interface (POST) in your service, and perform signature verification and idempotent processing as required in this document.
The interface path, authentication method, and response body format should be consistent with this document.

Recommendations
Only POST application/json is supported.
Implement idempotency for the same eventId: do not reprocess duplicate deliveries.
Use HTTPS; plain HTTP is not supported.

2. Security and Signature Verification

Signature Mechanism
The signature mechanism for Webhook is consistent with the HTTP response signature in the "Authentication" chapter:

Use the signKey you obtained during integration to perform HMAC (recommended HMAC-SHA512) on the signature string, then encode it with Base64.

W Checkout includes the signature and timestamp in the request headers. Merchants calculate and compare the signature using the same rules.

Request Headers

SIGNATURE: Base64(HMAC_SHA512(signKey, stringToSign))

TIMESTAMP: Millisecond-level timestamp (allows a ±2 minute deviation from the current time)

Signature String Construction
stringToSign = TIMESTAMP + RESPONSE_BODY_JSON

Note
Verify the difference between TIMESTAMP and local time; reject if it exceeds 2 minutes.
Deserialize the body and execute business logic only after signature verification passes.
If you are already using different header names (e.g., D-Signature) in the "Authentication" chapter, please keep them consistent with the current environment. The following examples use SIGNATURE/TIMESTAMP.

Java Code Example

3. Response and Retry Mechanism

Response Handling
After successfully processing a Webhook notification, you must return a JSON with a 200 status code, indicating the notification has been processed:

{
  "retcode": 200,
  "retmsg": "SUCCESS"
}

Retry Rules
If an HTTP 200 is not received, or a non-conforming JSON is returned, the system will retry according to the following intervals (total approximately 24h04m):

15s → 15s → 30s → 3m → 10m → 20m → 30m → 30m → 30m → 60m → 3h → 3h → 3h → 6h → 6h

Recommendations
Your interface should quickly return 200 before timing out and place the processing into an asynchronous queue.
Guarantee idempotency for each delivery (same eventId).

4. Event Data Structure

The basic Webhook event structure is as follows:

{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "CHECKOUT_ORDER_CHANGED",
  "timestamp": 1758701681,
  "data": { ... }  // Specific payload for each event type
}

Field Description

eventId: Unique event ID, used for idempotency.

eventType: Event type (see table below).

timestamp: Event generation time, in seconds.

data: Event data body.

5. Event Types and Examples

Enumerations and status values: For specific enumerations (e.g., orderStatus/refundStatus/settleStatus), please refer to the "Enumeration Reference Table" chapter.

5.1 Payment Order Changed — CHECKOUT_ORDER_CHANGED

{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "CHECKOUT_ORDER_CHANGED",
  "timestamp": 1758701681,
  "data": {
    "orderNo": "oxxxxxxx",
    "token": "ETH_USDT",
    "payingAmount": 989.19,
    "orderAmount": 989.19,
    "orderStatus": "PAID",
    "refundedAmount": 0,
    "createdTime": "2025-11-23 11:27:29",
    "updatedTime": "2025-11-23 11:27:29"
  }
}

5.2 Refund Order Changed — REFUND_ORDER_CHANGED

{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "REFUND_ORDER_CHANGED",
  "timestamp": 1758701681,
  "data": {
    "refundOrderNo": "xxxxxxx",
    "token": "ETH_USDT",
    "amount": "404.69",
    "refundStatus": "REFUNDED",
    "createdTime": "2025-01-25 00:48:39",
    "updatedTime": "2025-01-25 00:48:39"
  }
}

5.3 Settlement Order Changed — SETTLEMENT_ORDER_CHANGED

{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "SETTLEMENT_ORDER_CHANGED",
  "timestamp": 1758701681,
  "data": {
    "settlementOrderNo": "xxxxxxxx",
    "token": "ETH_USDT",
    "address": "0xxxxxxxxxxxx",
    "settlementAmount": "315.45",
    "settleStatus": "SETTLED",
    "createdTime": "2026-05-15 07:28:12",
    "updatedTime": "2026-05-15 07:28:12"
  }
}

5.4 Abnormal Payment — ABNORMAL_PAYMENT

Overpayment, underpayment, late payment, etc., can be handled via the refund process.

{
  "eventId": "evt_0a4fee0f8882",
  "eventType": "ABNORMAL_PAYMENT",
  "timestamp": 1758701681,
  "data": {
    "abnormalPaymentNo": "xxxxxxxx",
    "orderNo": "xxxxxxx",
    "token": "ETH_USDT",
    "amount": "818.89",
    "hash": "0xxxxxxxxxx",
    "pendingAmount": "739.00",
    "createdTime": "2025-12-23 12:56:47",
    "updatedTime": "2025-12-23 12:56:47"
  }
}

6. Troubleshooting and Security Recommendations

IP Whitelist (Optional): If conditions allow, you can apply for fixed outbound IP ranges from us, and merchants can verify source IPs.

Replay Protection: Strictly verify TIMESTAMP and signature; ensure idempotency for the same eventId.

Auditing and Alerts: Log original request headers, body, and verification results; trigger alerts for abnormal retries.

Performance Recommendations: Immediately return 200 after Webhook persistence/queuing to avoid duplicate deliveries due to long processing times.

1. Server Preparation#

2. Security and Signature Verification#

3. Response and Retry Mechanism#

4. Event Data Structure#

5. Event Types and Examples#

5.1 Payment Order Changed — CHECKOUT_ORDER_CHANGED#

5.2 Refund Order Changed — REFUND_ORDER_CHANGED#

5.3 Settlement Order Changed — SETTLEMENT_ORDER_CHANGED#

5.4 Abnormal Payment — ABNORMAL_PAYMENT#

6. Troubleshooting and Security Recommendations#

7. Webhook Sequence Diagram#