Webhook Asynchronous Notification#
Receives order status change callback notifications sent by the payment platform.
When the order status changes (such as payment success, payment failure, etc.), the platform will actively call the order callback interface to notify the merchant.
Signature Verification#
Webhook notifications must verify the signature to ensure authenticity. The verification principle is the same as request signature verification: use the platform App Secret to sign the raw payload, generate a sign, and compare it with the sign in the callback request header for validation.Since callback fields may be extended, it is recommended to convert JSON into a Map, and then use the data in the Map for signature verification. Avoid directly converting JSON into a class object and then using the object for signature validation.
| Header Name | Description | Example |
|---|
X-App-Id | Merchant application ID | app_platform_123 |
X-Ts | Unix timestamp (milliseconds, 13 digits) | 1699132800000 |
X-Nonce | Random string (anti-replay) | abcd1234efgh |
X-Sign | HMAC-SHA256 signature value (Base64 encoded) | a1b2c3d4e5f6... |
Retry Mechanism#
The platform will retry Webhook notifications according to the following strategy:| Retry Count | Delay Time | Description |
|---|
| 1 | Immediate | First attempt |
| 2 | 5 seconds | First retry |
| 3 | 30 seconds | Second retry |
| 4 | 2 minutes | Third retry |
| 5 | 10 minutes | Fourth retry |
| 6 | 1 hour | Fifth retry |
| 7 | 6 hours | Sixth retry |
| 8 | 16 hours | Seventh retry |
Merchants must return HTTP 200 status code within 5 seconds
If the merchant returns a non-200 status code or times out, the platform will trigger retries
Maximum 8 retries, total duration approximately 17 hours
Merchants should ensure webhook interface idempotency (via event_id)
Response Parameter Description#
Callback received successfully.
The merchant should return HTTP status code 200, and the response body should return the following string.Callback received and processing failed.
The merchant should return HTTP status code 200, and the response body should return the following string.