WEBHOOKS

回调机制 (Webhooks)

充值到账、提现状态变化、归集结果、链上事件等由派付主动 POST 推送到商户配置的回调地址。所有回调使用与调派付 API 一致的 HMAC-SHA256 签名，支持幂等处理和指数退避重试。

为什么必须用回调

链上事件是异步的——充值要等 N 个块确认，提现广播后还要等矿工打包。回调把"达到终态"的时刻直接 push 给商户，避免轮询带来的高延迟和资源浪费。接入派付必须实现回调接收端。

回调地址在管理后台配置

每个应用按 bizType 在管理后台分别配置回调 URL，不通过 Open API 设置。

投递模型

每当发生关注的事件，派付向商户配置的 endpoint 发送 POST 请求：

Content-Type：application/json; charset=utf-8
Headers：X-Api-Key / X-Timestamp（UNIX 毫秒 13 位）/ X-Nonce / X-Signature
ACK 判定：返回 HTTP 200 且 body 含 {"code":0} 或字符串 "success" / "ok"
重试：失败后指数退避（nextRetry = now + 60×2^retryTimes 秒），最多 10 次

充值 / 提现 / 归集 / 链上事件的字段定义、HMAC 验签算法与商户端代码示例。

按 bizType、bizId、status、时间范围分页查询回调任务；查看失败任务和下次重试时间。

按回调任务 id 查询每次推送的请求头摘要、响应 body、延迟等详情，用于排查失败原因。

按充值 id、提现业务单号或回调任务 id 手工触发重发，约 30 秒内由调度 Job 拉起推送。

bizType	说明
`RECHARGE`	充值生命周期事件。CONFIRMED 表示链上确认，PASS_THROUGH 应用以 SETTLED 作为业务最终入账依据。
`WITHDRAW`	提现状态变更（BROADCASTED / CONFIRMING / SUCCESS / FAILED），同一提现可能多次推送。
`COLLECT`	归集执行结果（SUCCESS / FAILED），仅用于资金对账、归集监控和异常排查。
`TRANSFER`	内部转账状态变更。
`CHAIN_EVENT`	链上事件订阅命中（合约日志等），仅当应用配置了链上事件订阅时推送。