开放平台新增 Webhook 事件推送

版本信息

[待补充：具体版本号与发布日期]

背景

原集成方式以"外部系统主动调用接口查询"（轮询）为主，存在两个问题：

• 实时性差（轮询间隔决定延迟）
• 无效请求多（大部分轮询没有新数据）

本次新增 Webhook，让 MES 主动推送事件。

新增：事件订阅

支持的事件

事件清单可按需扩展，[待补充：完整事件清单]。

订阅配置

外部系统可配置：

• 订阅哪些事件
• 推送地址（URL）
• 认证方式
• 推送格式
• 重试策略

推送机制

推送格式：JSON，包含事件类型、业务主键、事件数据、时间戳、事件 ID。

重试策略：推送失败时按退避策略重试（如 1min、5min、30min），超过次数进入失败队列。

幂等要求：接收方应按事件 ID 去重（可能收到重复推送）。

新增：推送监控

提供推送的监控与排查能力：

"失败列表"很重要：网络或对方系统异常导致的失败，需要能重推。

新增：签名验证

推送请求带签名，接收方可验证来源：

• 使用共享密钥 + 时间戳 + 请求体计算签名
• 接收方验证签名与时间戳（防重放）

建议生产环境启用签名验证。

优化改进

使用建议

建议一：Webhook + 接口查询结合

推荐模式：

1. Webhook 收到事件通知（只含主键）
2. 接收方调用查询接口获取详细信息
3. 处理完成后返回确认

这样推送内容小、传输快，且能保证数据完整。

不建议在 Webhook 里传全部数据。

建议二：接收方必须做幂等

推送可能重复（网络重试）。接收方按事件 ID 去重是必须的。

建议三：要有失败处理机制

对方系统不可用是常态。建议：

• 失败重试
• 超过重试次数进入人工处理队列
• 定期核对两边数据（对账）

建议四：监控推送成功率

推送成功率应该作为集成健康度的核心指标。

如果成功率持续下降，说明集成链路有问题，需要及时处理。

建议五：控制推送频率

高频事件（如报工）可能大量推送，对接收方造成压力。

建议支持聚合推送（比如每分钟汇总一次），或按事件类型分别配置。

注意事项

• Webhook 是"至少一次"投递语义，接收方必须支持幂等
• 推送地址需能从 MES 服务器访问（网络可达）
• 建议对推送地址配置 IP 白名单或签名校验
• 事件顺序不保证，接收方应按业务时间戳排序处理

具体的订阅配置与事件清单，[待补充：产品团队补充开放平台文档]。