妙手ERP事件直推：订单变更秒级同步

2026 年 5 月 17 日，妙手ERP 3.2.8 版本开放 Webhook 事件推送：订单创建、支付、改址、审核、发货、退款等 18 类事件可实时推送到企业自有系统，支持 HMAC 签名校验、失败重试与推送日志。上线首月日均推送 240 万条，平均延迟 0.4 秒，推送成功率 99.97%。

事件类型与订阅配置

事件分订单、库存、商品、售后四组共 18 类。订单组包含创建、支付、改址、审核通过、发货、签收、取消；库存组包含扣减、回补、盘点调整；商品组包含价格变更、上下架；售后组包含退款申请、退货入库、换货出库。

订阅按应用维度配置，每个应用可订阅不同事件并设置独立回调地址。同一事件可推送多个地址，例如订单创建同时推给 WMS 与 BI。妙手ERP 开放平台负责人陈慕说：「推送不是广播，谁需要什么就订什么，否则接入方会被无关事件淹没。」

签名校验与失败重试

每次推送带时间戳、随机串与 HMAC-SHA256 签名，接入方用密钥校验，签名不符直接拒绝。时间戳超过 5 分钟视为过期，防止重放攻击。密钥支持轮换，轮换期间新旧密钥同时有效 24 小时。

接入方需在 5 秒内返回 2xx，超时或非 2xx 视为失败，按 10 秒、1 分钟、5 分钟、30 分钟、2 小时五次重试。五次均失败则进入死信队列，保留 72 小时，可在控制台手动重推。推送日志记录请求体、响应码、耗时与重试次数。

延迟与成功率的实测数据

上线首月、日均 240 万条、接入 116 家企业。平均推送延迟 0.4 秒，P99 延迟 1.8 秒；成功率 99.97%；死信率 0.03%，主要集中在接入方服务重启期间；轮询改造为推送后，接入方接口调用量下降 86%，订单同步时效从 5 分钟提升到秒级。

剩余失败多因接入方未做幂等处理，重试时重复创建订单。文档中已明确要求以事件 ID 做幂等键。建议接入方先用测试环境跑满 18 类事件，确认签名校验与重试逻辑无误后再切生产。

对接方怎么验证推送没丢

两种方式结合：一是让对接方按事件编号去重并回执，未回执的进入重试队列；二是每天对一次总量，按事件类型比对推送条数与消费条数，差异超过千分之一就查死信队列。只看单次返回成功不够，消费端处理失败也会丢数据。

签名校验不能省。用约定的密钥对时间戳与报文签名，接收方校验失败直接拒绝，避免伪造推送。时间戳超过五分钟的请求也拒绝，防止重放。试点日均 240 万条推送，成功率 99.97%，剩下的基本都能在死信队列里找到。

推送内容要够用但不能过量。订单变更只推变更字段与关键标识，不要整单推送，接收方解析成本高，也容易超时。字段清单在文档里固定下来，加字段走版本，不要悄悄改结构。

文档要写清楚重试语义。同一事件可能被推送多次，接收方必须按事件编号做幂等处理；重试间隔与最大次数也要写明，否则对接方会按一次推送来设计，重复数据入库后很难清理。字段变更走版本号，新增字段保持向后兼容，不要中途改名或改类型。事件要能按店铺过滤。一个接收地址订阅全部店铺，数据量会很大，也没必要。订阅时指定店铺范围与事件类型，接收方只处理与自己相关的部分，压力和误判都会少很多。

推送不是广播，谁需要什么就订什么，否则接入方会被无关事件淹没。

Webhook 事件推送已随 3.2.8 版本上线，企业版可用，需在开放平台创建应用获取密钥。后续将支持事件回放与按事件类型统计消费延迟。已有自建 ERP 或 WMS 的团队，可在下载中心获取客户端后从「开放平台 - 事件订阅」查看接口文档。