Webhook Notification Mechanism Description

Overview

This Webhook notification mechanism is used to send event notifications to the specified callback URL and considers it successful upon receiving an HTTP 200 response. If the notification fails, exponential backoff will be used for retries.

Webhook Request

• Request Method: POST
• Request Headers (Example):

timezone: Asia/Shanghai
signature:h8zwMT0uBQJa/IDCg4ifIOchBFft9AvLkokjrrIiYtkf8fsk3A8wDqSdB2c66ks9gJqARafZ0MygnWOUU9NbVPCUixHvDFl8Z3238ADzhb29+S4S3fn7XTFV7DUtCMd9aFUvKLXGr6z4/GBog80yynGHDL6Ygjde7xI9D/x/OXiLOBGN1AuopTj7zL6TEvp/646T5PzZg8w9pnWA7r4ZxHplZrG0SKTLtZRloCtLk3kC3EwI0/m8obG4pptiPjY/8PuuLQUzbaPfd57wQP7tLUEhTr0LY2hSRYbdAtHwiPcmMY9QoW0rnHj/a/4nCqZNTrBwqiHJhdsKEZflA2KPjw==
timestamp:1742311500484
DD-Request-Id:req_oVJMRLT7dzs8inRB9xYTYuLo

• Request Body (Example):

{
    "data": {
        "id": "pi_aDNwWGfls1vcPLUHJDykYwmR",
        "amount": 7698,
        "result": {
            "result_code": "FAILED",
            "result_status": "F",
            "result_message": "card_velocity_exceeded"
        },
        "currency": "USD",
        "merchant_id": "acct_8NRyElotSW15F08m",
        "merchant_order_id": "21064044592225646561337"
    }
}

• Response Requirements:
• When the receiver returns HTTP 200, it means the notification is successful and no retry is needed.
• Any non-200 HTTP status code (such as 400, 500) or timeout will be considered a failure and trigger the retry mechanism.

Failure Retry Mechanism

If the Webhook delivery fails, an Exponential Backoff strategy will be used for retries. The retry intervals are as follows:

Retry Count	Retry Interval
1st time	30 seconds
2nd time	60 seconds
3rd time	120 seconds
4th time	24 hours (86400 sec)
5th time	48 hours (172800 sec)

• Maximum 5 retries. If it still fails, no further notifications will be sent and manual intervention is required.
• Before each retry, the Webhook system will resend the request with the same event data.
• If any retry succeeds (returns HTTP 200), all subsequent retries are cancelled.

Response Handling

HTTP Status Code	Handling
200 OK	Considered successful, stop retrying
Non-200 (including 4xx/5xx)	Considered failed, trigger exponential backoff retry
Timeout	Considered failed, enter retry process

• Successful response (HTTP 200): Webhook is processed, no further retries.
• All non-200 responses (including 4xx and 5xx): Whether client error (4xx) or server error (5xx), will trigger retry.
• Timeout: If the receiver does not respond within the specified time, Webhook is considered failed and enters the retry process.

Request De-duplication Logic

• The Webhook request header contains a unique DD-Request-Id to identify each notification.
• The receiver should store the DD-Request-Id and check if it has already been processed:
  • If already processed, directly return 200 OK to avoid duplicate execution.
  • If not processed, execute as normal and record the DD-Request-Id to prevent subsequent duplicate requests from being executed again.

Signature Verification

To ensure the data integrity and security of Webhook requests, please refer to the Signature and Verification documentation to ensure the request has not been tampered with.