Webhook 通知

概述

本 Webhook 通知机制用于向指定的回调 URL 发送事件通知，并在收到 HTTP 200 响应时视为成功。如果通知失败，将采用 指数级退避 进行重试。

Webhook 请求

请求方式：POST
请求头（示例）：

http

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

请求体（示例）：

json

{
    "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"
    }
}

响应要求：
当 接收方返回 HTTP 200 时，表示通知成功，无需重试。
任何 非 200 的 HTTP 状态码（如 400、500）或超时都将视为失败，触发重试机制。

失败重试机制

如果 Webhook 发送失败，将采用 指数级退避（Exponential Backoff） 策略进行重试。重试时间间隔如下：

重试次数	重试间隔时间
第 1 次	30 秒
第 2 次	60 秒
第 3 次	120 秒
第 4 次	24 小时（86400 秒）
第 5 次	48 小时（172800 秒）

最多重试 5 次，如果仍然失败，则不再进行通知，需人工介入处理。
每次重试前，Webhook 系统会重新发起请求，并附带相同的事件数据。
在重试过程中，如果某次请求成功（返回 HTTP 200），则后续所有重试取消。

响应处理

HTTP 状态码	处理方式
`200 OK`	视为通知成功，停止重试
非 200（包括 4xx 和 5xx）	视为通知失败，触发指数级退避重试
超时	视为失败，进入重试流程

成功响应（HTTP 200）：Webhook 处理完成，系统不再重试。
所有非 200 响应（包括 4xx 和 5xx）：无论是客户端错误 (4xx)，还是服务器错误 (5xx)，都会触发重试。
超时（Timeout）：如果接收方在规定时间内未响应，Webhook 视为失败，进入重试流程。

请求去重逻辑

Webhook 请求头包含唯一 DD-Request-Id，用于标识每次通知。
接收方应存储 DD-Request-Id 并检查是否已处理：
- 若已处理，直接返回 200 OK，避免重复执行。
- 若未处理，正常执行，并记录 DD-Request-Id，防止后续重复请求被再次执行。

签名验证

为了确保 Webhook 请求的数据完整性和安全性，请参考签名和验签文档，确保请求未被篡改。

Webhook 通知 ​

概述 ​

Webhook 请求 ​

失败重试机制 ​

响应处理 ​

请求去重逻辑 ​