Webhook

W Checkout Webhook 用于向商户推送订单/退款/结算/异常支付等事件，便于客户系统实时更新业务状态与对账。

1. 服务端准备

请在您的服务中实现一个可被公网访问的 Webhook 接口（POST），并按本文要求进行验签与幂等处理。
接口路径、鉴权方式与返回体格式应与本文保持一致。

建议
仅支持 POST application/json。
对相同 eventId 做幂等：重复投递时不重复处理。
采用 HTTPS，不支持明文 HTTP。

2. 安全与验签

签名机制
Webhook 的签名机制与“鉴权章节”中的HTTP 响应签名一致：

使用你方在接入时获得的 signKey 对签名字符串做 HMAC（推荐 HMAC-SHA512），再进行 Base64 编码。

W Checkout 在请求头中携带签名与时间戳，商户按相同规则计算并比对。

请求头（Headers）

SIGNATURE: Base64(HMAC_SHA512(signKey, stringToSign))

TIMESTAMP: 毫秒级时间戳（与当前时间允许 ±2 分钟误差）

签名字符串构造
stringToSign = TIMESTAMP + RESPONSE_BODY_JSON

注意
验证 TIMESTAMP 与本地时间差；超出 2 分钟拒绝处理。
验签通过后再反序列化 body 并执行业务逻辑。
若你方已经在“鉴权章节”采用不同的 header 名（如 D-Signature），请与当前环境保持一致；以下示例沿用 SIGNATURE/TIMESTAMP。

Java 代码示例

3. 返回与重试机制

返回处理
成功处理完Webhook通知后，需要以200状态码返回一个JSON，表示已经完成通知的处理：

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

重试规则
若未收到 HTTP 200，或返回非上述 JSON，系统将按如下间隔重试（总计约 24h04m）：
15s → 15s → 30s → 3m → 10m → 20m → 30m → 30m → 30m → 60m → 3h → 3h → 3h → 6h → 6h

建议
您的接口应在超时前快速返回 200，并将处理放入异步队列。
对每次投递（同一 eventId）保证幂等。

4. 事件数据结构

Webhook 基本事件结构如下：

{
"eventId": "evt_0a4fee0f8882",
"eventType": "CHECKOUT_ORDER_CHANGED",
"timestamp": 1758701681,
"data": { ... }  // 各事件类型的具体负载
}

字段说明

eventId：事件唯一 ID，用于幂等。

eventType：事件类型（见下表）。

timestamp：事件产生时间，单位秒。

data：事件数据体。

5. 事件类型与示例

枚举与状态值：具体枚举（如 orderStatus/refundStatus/settleStatus）请参考《枚举对照表》章节。

5.1 支付订单变更 — 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

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

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

多付、少付、晚付等，可通过退款流程处理

{
  "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. 故障与安全建议

IP 白名单（可选）：若有条件，可向我方申请固定出口段，商户侧对来源 IP 进行校验。

重放防护：严格校验 TIMESTAMP 与签名；对相同 eventId 幂等。

审计与告警：记录原始请求头、body 与验签结果；异常重试触发告警。

性能建议：Webhook 落盘/入队后立即返回 200，避免长耗时导致重复投递。

1. 服务端准备#

2. 安全与验签#

3. 返回与重试机制#

4. 事件数据结构#

5. 事件类型与示例#

5.1 支付订单变更 — CHECKOUT_ORDER_CHANGED#

5.2 退款单变更 — REFUND_ORDER_CHANGED#

5.3 结算单变更 — SETTLEMENT_ORDER_CHANGED#

5.4 异常支付 — ABNORMAL_PAYMENT#

6. 故障与安全建议#

7.Webhook 时序图#