文档 · 通用规则
Webhook 推送
回调地址是可选的:在开放平台控制台「应用 → 凭证与安全」里填上你的服务端 HTTPS 地址后,订单状态变化会主动推给你,不用高频轮询;不配就不推送,用查询接口取状态即可。消费者购物付款后要跳回你的页面(returnUrl)时也需要它:returnUrl 须在这个域名或其子域下。
order.status:订单状态变化,所有场景都有。员工福利与企业采购的推送(含员工付现金后付清)带source: "enterprise"和归一化后的status/prevStatus(如PAID、SHIPPED、DELIVERED、COMPLETED、CANCELED、REFUNDED);消费者购物的推送带上游事件名sourceEvent,收到后查订单详情取最新状态。order.result:消费者购物的订单在上游建单出了终态时推送(PLACED已建单 /FAILED建单失败)。退款由平台自动完成,你只需查收款单同步状态,不要自己给用户退款。- 回调签名使用五段签名串:
时间戳 \n POST \n 回调地址的路径 \n sha256(请求体) \n 空串,再做 HMAC-SHA256。 - 至少投递一次:失败会退避重试 3 次,可能重复,请幂等处理。5 秒内返回 2xx 即视为成功。
- 推送是加速通道,不是唯一通道:请保留定时查询订单作为兜底。
回调配置在 appKey 上,REST 与 MCP 两种接入方式下单的订单都会推送。
1POST <你的 callback_url>2x-timestamp / x-nonce / x-signature3 4{5 "event": "order.status",6 "source": "enterprise",7 "orderId": "4012xxxxxxxx",8 "outerPurchaseOrderId": "your-order-20261014-0001",9 "status": "SHIPPED",10 "prevStatus": "PAID",11 "appKey": "ak_…",12 "ts": 176040000013}