通知
当订单状态发生变更时，HashNut 会向您的服务器发送 Webhook 通知。本页介绍通知载荷、签名验证和重试策略。
Webhook 投递
当订单状态变更时（例如从 INIT 变为 PAID，或从 CONFIRMING 变为 SUCCESS），HashNut 会向该订单配置的 Notify URL 发送 HTTP POST 请求。
通知载荷
通知体设计为最小化，仅包含查询完整订单详情所需的标识信息：
json
{
"payOrderId": "PO202606210001",
"merchantOrderId": "ORDER-20260621-001",
"accessSign": "BASE64_HMAC_SIGNATURE",
"state": 3
}| 字段 | 类型 | 说明 |
|---|---|---|
payOrderId | string | HashNut 订单 ID |
merchantOrderId | string | 您的唯一订单标识符 |
accessSign | string | 用于查询订单的 HMAC-SHA256 签名 |
state | integer | 新的订单状态。参见订单状态 |
通知请求头
通知请求包含 HMAC 签名请求头（与身份认证格式相同）：
| 请求头 | 说明 |
|---|---|
hashnut-request-uuid | 本次通知的 UUID |
hashnut-request-timestamp | Unix 时间戳（毫秒） |
hashnut-request-sign | uuid + timestamp + body 的 Base64 编码 HMAC-SHA256 签名 |
签名验证
DANGER
处理通知前务必验证 hashnut-request-sign 请求头。接受未验证的通知会使您的系统面临伪造攻击风险。
验证步骤：
- 读取
hashnut-request-uuid、hashnut-request-timestamp和hashnut-request-sign请求头。 - 读取原始请求体字符串。
- 拼接：
signString = uuid + timestamp + body - 使用您的 Secret Key 计算
base64( hmac_sha256( secretKey, signString ) )。 - 将计算结果与收到的
hashnut-request-sign比对。
推荐商户处理流程
收到通知后：
- 验证请求头签名（如上所述）。
- 查询完整订单详情：使用通知体中的
payOrderId、merchantOrderId和accessSign调用查询订单 API。 - 更新您内部系统的订单状态（以查询结果为准）。
- 返回字符串
success确认收到。
TIP
不要仅依赖通知中的 state 字段来执行业务逻辑。务必调用查询订单 API 获取完整且权威的订单数据（金额、交易哈希等）。
响应要求
您的 Notify URL 端点必须返回纯文本字符串 success（HTTP 200）以确认收到通知。
HTTP/1.1 200 OK
Content-Type: text/plain
successWARNING
如果您的端点未返回 "success"，HashNut 会将该通知视为失败并进行重试投递。
重试策略
| 重试次数 | 距上次间隔 |
|---|---|
| 第 1 次重试 | 15 秒 |
| 第 2 次重试 | 30 秒 |
| 第 3 次重试 | 1 分钟 |
| 第 4 次重试 | 5 分钟 |
| 第 5 次重试 | 30 分钟 |
| 第 6 次重试 | 1 小时 |
| 第 7 次重试 | 6 小时 |
7 次重试后（总计约 8 小时），HashNut 停止重试。如果您错过了通知，可以使用查询订单来轮询当前状态。
Notify URL 与 Callback URL 的区别
这两个 URL 有完全不同的用途，请勿混淆。
| Notify URL | Callback URL | |
|---|---|---|
| 方向 | HashNut 后端 --> 您的后端 | 客户浏览器 --> 您的前端 |
| 用途 | 服务器到服务器的 Webhook 通知 | 支付完成后的前端跳转 |
| 传输方式 | 带 JSON 载荷的 HTTP POST | 浏览器重定向（302 或 JS 重定向） |
| 认证 | 请求头 HMAC 签名 | 无签名 |
| 可靠性 | 失败时重试 | 单次重定向，不重试 |
| 示例 URL | https://api.yoursite.com/api/notify | https://yoursite.com/payment-result |
TIP
务必实现 Notify URL 以可靠地跟踪订单状态。Callback URL 是可选的，仅用于改善客户支付后的前端体验。