Webhook

触发时机

系统在订单 status=PAID 且达到配置确认数后，向创建订单时的 notifyUrl 发起 POST。

请求头与验签

验签使用商户 Webhook Secret（不是 API Secret）：

expected = HMAC-SHA256(webhookSecret, t + "." + rawBody).hex()

与 X-Influx-Signature 中的 v1 做常量时间比对。

头	说明
X-Influx-Event	固定为 payment.paid
X-Influx-Signature	形如 t=1714291800,v1=<hex>
X-Influx-Delivery	本次投递唯一 ID，建议用于幂等

警告

rawBody 必须是原始 HTTP body 字节，不要先 JSON.parse 再 stringify。

请求示例

POST https://merchant.example.com/webhook
Content-Type: application/json
X-Influx-Event: payment.paid
X-Influx-Signature: t=1714291800,v1=abc123...
X-Influx-Delivery: dl_01HYYY...

{
  "event": "payment.paid",
  "paymentId": "p_01HXXX...",
  "orderNo": "ORDER-20260428-0001",
  "txId": "abc123def456...",
  "tokenSymbol": "USDT",
  "paymentNetwork": "TRC20",
  "amount": "10.50",
  "amountRaw": "10500000",
  "blockNum": "62000000",
  "confirmations": 8,
  "paidAt": "2026-04-28T16:32:10.000Z"
}

blockNum / confirmations 无链上记录时可能为 null。

你方响应

请在 5 秒内返回 HTTP 2xx（body 可为空）。非 2xx 或超时将按队列重试（最多 8 次，指数退避）。

HTTP/1.1 200 OK
Content-Type: application/json

{ "ok": true }

body 内容可自定义，只要状态码为 2xx 即视为成功。

幂等

请用 X-Influx-Delivery 或 paymentId 做幂等，避免重复入账。

验签伪代码

rawBody = 原始 HTTP body 字节
parse X-Influx-Signature -> t, v1
expected = HMAC-SHA256(webhookSecret, t + "." + rawBody).hex()
assert timing-safe-equal(v1, expected)