签名不匹配
最常见原因是对解析后的 JSON 签名，而不是精确原始 body，或使用了与请求头不同的时间戳。
Webhook 测试器
调试 Webhook 回调让签名对得上
编辑示例请求体，生成 HMAC-SHA256 签名与 cURL 请求。在您的测试环境，核对回调验签逻辑。
01
配置测试参数
填写接收地址、测试密钥和时间戳。
签名在浏览器中计算。调试时请使用测试密钥。
Unix 时间戳，单位为毫秒。与 BoltUtil 回调请求头保持一致。
02
编辑请求体，生成签名
修改 JSON 后，签名与 cURL 会同步更新。
生成的签名
HMAC-SHA256填写测试密钥、有效时间戳和 JSON 后生成签名。
根据当前时间戳、请求体原文与测试密钥计算。
JSON 格式有效
cURL / POST测试请求
填写有效地址、密钥、时间戳和 JSON 后生成请求。这是模拟的 USDC 订单回调，可改为 USDT。订单、地址与交易哈希均为示例，不代表真实付款。
本工具只生成请求，不会自动发送。请在您的测试环境手动执行 cURL。
HMAC_SHA256(timestamp + "." + rawBody, secret)- 01
保留原始请求体
用请求头中的毫秒时间戳和原始请求体计算 HMAC，再解析 JSON。空格、换行和字段顺序都会影响签名。
- 02
核对签名
使用回调地址配置的 Webhook 密钥，并用运行时提供的恒定时间比较函数核对签名。
- 03
安全记录，再返回 2xx
验签通过并将事件写入数据库或可靠队列后，返回 HTTP 2xx。更新业务订单时需处理重复投递。
Webhook 排查
对不上？从这里检查
从请求原文、密钥和响应状态入手，逐项定位问题。
密钥错误
请使用商户回调地址配置的 Webhook 密钥。API Key 和 Webhook Secret 应视为不同凭证。
Body 解析器改变了载荷
JSON 中间件可能重排或格式化 payload。校验 HMAC 前应先捕获原始 body。
接口返回非 2xx
非 2xx 响应会被记为投递失败。是否再次投递取决于回调类型、响应状态和重试策略。
处理逻辑不幂等
同一通知可能重复投递。按实际回调的订单标识及状态，或唯一事件 ID 去重，避免重复发货或开通服务。
持久化前返回成功
只有在事件写入数据库或队列后才返回 HTTP 2xx，否则服务崩溃可能丢失已完成支付通知。
常见问题
调试时，您可能想知道
验签、响应与重复投递，几个常见问题。
为什么 Webhook 签名校验失败？
请验证精确原始请求 body、时间戳请求头和配置的 Webhook 密钥。对解析后的 JSON 或重新格式化后的 body 签名通常会得到不同 HMAC。
Webhook 接口必须在响应体返回 SUCCESS 吗？
不需要。BoltUtil 依据 HTTP 状态码判断投递结果：2xx 表示接收成功，响应体不必写 SUCCESS。请先验签并安全记录事件。
如何处理重复 Webhook 投递？
使用数据库唯一约束或原子操作去重。传统订单回调可使用订单标识与状态；包含唯一事件 ID 的回调可使用该 ID。不要只依赖交易哈希，它可能对应多笔转账。
什么时候应该返回 HTTP 2xx？
验签通过并将事件安全写入数据库或可靠队列后，再返回 2xx。验签失败或保存失败时应返回合适的错误状态；是否重试取决于回调类型和重试策略。