商数通开放平台

主题

回调通知 ​

商数通开放平台通过回调通知（Webhook）向您推送事件消息，实现实时数据同步。

工作原理 ​

┌─────────────┐                    ┌─────────────┐
│   平台服务   │ ────── POST ─────► │  您的服务器  │
└─────────────┘    JSON Payload    └─────────────┘

当特定事件发生时（如支付成功、订单状态变更等），平台会向您的回调地址发送 HTTP POST 请求。

回调地址配置 ​

在 应用管理 中配置回调地址（notifyUrl），要求：

  • 必须为 HTTPS 协议
  • 响应时间不超过 5 秒
  • 返回 HTTP 200 表示接收成功

通知格式 ​

请求头 ​

字段说明
Content-Typeapplication/json
X-Event-Type事件类型
X-Timestamp时间戳（秒）
X-Sign签名（用于验签）

请求体示例 ​

json
{
  "eventType": "PAYMENT_SUCCESS",
  "timestamp": 1709280000,
  "data": {
    "tradeNo": "10086",
    "outTradeNo": "ORDER20260310001",
    "tradeStatus": "SUCCESS",
    "totalAmount": 29900,
    "payTime": "2026-03-10T15:02:00+08:00"
  }
}

事件类型 ​

事件类型说明
PAYMENT_SUCCESS支付成功
PAYMENT_CLOSE支付关闭
REFUND_SUCCESS退款成功
ORDER_STATUS_CHANGE订单状态变更

验签 ​

收到回调通知后，请按 签名算法 验证签名，确保请求来自平台。

javascript
// 验签示例
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSign = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return expectedSign === signature;
}

重试机制 ​

如果您的服务器未返回 HTTP 200，平台会进行重试：

重试次数间隔时间
第 1 次1 分钟
第 2 次5 分钟
第 3 次15 分钟
第 4 次30 分钟
第 5 次1 小时

超过 5 次重试后，通知将被丢弃。您也可以通过 API 主动查询订单状态。

最佳实践 ​

  1. 异步处理：收到通知后立即返回 200，业务逻辑放入队列异步处理
  2. 幂等处理：同一事件可能重复推送，请确保业务逻辑幂等
  3. 验签必须：务必验证签名，防止伪造请求
  4. 日志记录：记录所有回调通知，便于问题排查

商数通开放平台

Copyright © 2026 商数通科技