Webhook 回调怎么配？事件、重试、验签

先想明白你要不要它

没有回调，你的系统想知道「会话结束了没、工单转状态了没」，只能定时去问。问得勤了浪费资源，问得疏了又有延迟。Webhook 反过来：你在美洽配一个接收地址，事件一发生它就 POST 一份数据过来。适合这些场景：工单状态同步进内部系统、会话结束自动触发满意度短信、新会话实时推上你们的监控大屏。只是偶尔看看数据的话，用不上它。

跟着配 五步接进来

1. 在你的服务端写一个接收接口，公网能访问，上 HTTPS，内网地址对方够不着。
2. 到美洽后台的回调配置处填上这个地址，勾选你关心的事件，入口位置以后台实际显示为准。
3. 收到请求先验签，验过了再解析事件类型和数据。
4. 处理逻辑写轻一点，收到尽快回成功响应，重活丢给后台任务慢慢干。
5. 发一条测试事件，全流程走一遍：能收到、能解析、同一个事件不会重复执行。

验签、重试、幂等 一个都不能省

• 验签：你的地址挂在公网上，谁都能往里 POST 假数据。按官方给的方式校验签名，验不过的直接丢弃，别心软。
• 重试：你没及时回成功，对方一般会判失败再推几次，这是正常机制，不是出了 bug。
• 幂等：既然会重推，同一个事件可能到好几次。拿事件里的唯一标识做去重，处理过的直接回成功但不再执行，免得重复发短信、重复建单。

还有个别扭情况：事件明明收到了，解析却报错。多半是你按旧文档写的解析逻辑，字段名或结构后来变了。解析时做得宽容点，不认识的字段跳过，别因为一个字段对不上就把整个请求作废。

收不到回调怎么查

先翻你服务端的访问日志，把问题劈成两半：一种是请求压根没到你的服务器，一种是到了但你这边没处理妥当。没送到，查地址是不是公网可达、HTTPS 证书有没有问题、防火墙是不是把对方来源挡了。送到了没处理好，查接口是不是处理太慢被判超时、验签逻辑是不是把正常请求也误杀了、程序是不是悄悄报错。一层层剥，很快能定位。

平时怎么防

给接收接口加个简单监控：一天下来一个事件都没收到，就该警觉了，要么是真没量，要么是链路断了。还有，回调地址改了、证书换了，记得同步去后台更新配置，这类「忘了改」是最常见的断因。