Webhook 可靠性

接收 Webhook 要做到不丢、不重、不卡：收到推送后先校验、保存，再马上返回成功；耗时的业务处理交给后台任务。

接收流程

收到推送 → 校验来源（开启时） → 按事件 ID 去重 → 存进数据库或队列 → 返回 2xx
                                                          ↓
                                                后台任务处理业务与重试

必做项

项目	要求
地址	公网能访问的 HTTP 或 HTTPS 完整地址；正式环境用 HTTPS
尽快返回	保存成功后立即返回 2xx，数据库慢操作和第三方调用放进队列；用兼容接口设置的地址，推送超时为 6 秒
保存失败不返回成功	没保存好就返回 2xx，这条推送会被当成已收到
去重	推送可能重复。控制台配置的地址按请求头 X-Eyun-Event-Id 去重；消息按账号与 newMsgId 去重
可观测	记录事件类型、事件 ID、耗时、处理结果和重试次数
数据最小化	日志只保留排查必需的字段，敏感内容脱敏或不记录

来源校验

• 在控制台「收进来」配置的地址：可以点「生成密钥」开启。之后每条推送的 X-Eyun-Signature 就等于你配置的密钥，接收端用常量时间比较即可。个人微信不计算 HMAC，不要套用企业微信的 sha256= 算法。详见设置回调地址。
• 用兼容接口 /setHttpCallbackUrl 设置的地址：没有定义签名头。需要来源校验时请联系客服确认，不要自己推导签名字段。

开发阶段先按Webhook 本地联调验证事件，再按回调事件索引建立分发规则。