美洽Webhook推送失败排查示意:收不到新对话时先核对接地址、密钥和创建对话事件

美洽Webhook推送失败怎么排查:收不到新对话通知时的逐项检查

业务系统突然收不到美洽的新对话通知时,先不要改入库代码。打开工作台「设置 → 开发者 → Webhooks」,先核三件事:回调地址有没有写错,密钥是否还和接收方一致,事件列表里有没有勾选「创建对话」。核完再分清两条路:美洽根本没把请求打到你的服务器,还是请求已经到了,只是你们处理失败、返回了非成功状态,或在规定时间内没有返回状态码。官方目前失败后暂无重试,修好之前先用工作台人工盯新对话和留言,避免漏接待。

这篇文章只讲已经配过推送、却突然收不到新对话时怎么逐项排查,不重复从零填写地址、勾选主题的入门步骤。和「新对话通知」最直接对应的主题是「创建对话」,不要拿「结束对话」「更新对话」或「首次分配客服」来判断新对话有没有推出去。查的时候每改一项就做一次小验证,避免同时改地址、密钥和代码,最后说不清是哪一步修好的。

先确认:是美洽没推到,还是接到后处理失败

排障最容易走弯路的地方,是把两种完全不同的故障当成同一件事。第一种是美洽这一侧没有成功把请求送到你填写的地址,接收方访问日志里看不到对应请求。第二种是请求已经到达,但接口返回了不是 200 的状态码,或者在返回前卡住、超时,没有给出状态码,美洽会把这一次视为推送失败。还有一种容易误判的情况:接收接口很快返回了 200,可后面的写库、通知逻辑自己报错,业务系统里看不到新对话,这时美洽侧其实已经视为成功,问题在你们自己的后续处理。

先看接收方服务器在出问题的那几分钟有没有接到请求、返回了什么状态码、是否超时。这是区分「没打到」和「打到了但失败」的最直接依据。若你当前环境的 Webhooks 设置页正好有发送记录、失败提示或测试按钮,再把那边的结果和接收日志对照;具体有没有这些入口,以实际界面为准。没有这类记录时,不要凭感觉改配置,用一条测试对话加上接收方日志来分辨。

  1. 约定一个测试时间,由同事在美洽里发起一条不会打扰真实客户的测试对话,触发「创建对话」。同时打开接收服务的访问日志和错误日志,看有没有在同一时刻到达的请求,以及返回耗时和状态码。
  2. 若完全没有请求进入,优先去查回调地址、网络和证书,而不是先改业务代码。若请求到了但状态码不是 200,或日志里出现超时断开,就转向接口实现、鉴权和返回时机。
  3. 若请求已到且状态码是 200,但业务库没有落下这条对话,说明推送在美洽看来已经成功,要把排查重点转到你们自己的解析、校验和写库逻辑,这一条不能再当成「推送失败」来改美洽配置。

先核对美洽里现有的推送配置(以当前版本为准)

很多「突然收不到」其实不是服务器挂了,而是配置被改过却没人同步。核对时只对照当前正在使用的这一条推送,不要重新走一遍完整的填写教程。打开工作台「设置 → 开发者 → Webhooks」,把回调地址、密钥和已勾选的主题,逐项跟接收方手里的配置表对一遍,对不上的先记下来再改,不要同时改三项。

回调地址、密钥和勾选的事件类型

回调地址要和接收服务实际监听的路径完全一致。访问协议、端口有没有写、路径中间是否多了一段、末尾斜杠多一个或少一个,都可能导致请求打到别的路由,甚至根本到不了你的接口。改过网关、反向代理或发布路径之后,最容易出现这种「以前能通、发版后突然没了」的情况。密钥就是用来校验请求头 Meiqia-Signature 的那串值,美洽侧和接收侧必须是同一份。

和「新对话通知」直接相关的主题是「创建对话」,对应标识为 conversation.created。如果只勾了「结束对话」conversation.closed,业务系统当然不会在新对话进来时收到通知。相关但并不等于新对话的还有:客服修改对话小结时的「更新对话」conversation.updated,以及「首次分配客服」conversation.scheduled。另外还有顾客、通话、工单等主题,不要把它们和新对话混为一谈。没有在官方主题里核实过的事件,不要当成已经订阅的依据。

  1. 把后台里保存的完整回调地址复制出来,和接收服务的路由配置并排比对:访问协议、主机名、端口、路径、末尾斜杠,任何一处不一致都先改到完全相同,再进行下一步。
  2. 打开事件勾选列表,确认「创建对话」处于选中状态。若你只在等新对话,却发现只订了结束、更新或分配类主题,补勾「创建对话」后不要立刻宣布修好,还要用测试对话验证。
  3. 如果近期有人改过网关路径或证书,同时核对这些改动是否只发布到了预发、生产地址却还写着旧路径。地址对了但证书链不完整,表现也会是请求到不了或握手失败。

近期是否轮换过密钥却忘了改业务系统

密钥一旦在美洽里轮换,接收方必须同步换成新值,否则签名校验会失败。官方的校验方法是:把原始请求体字符串与密钥拼接,请求体在前、密钥在后,计算 SHA1,再和请求头 Meiqia-Signature 比对。只改了美洽、业务系统还在用旧密钥,接收端会判定签名不合法;如果这时返回了拒绝或错误状态,美洽就会把这次推送记为失败。只改了业务系统、美洽还是旧密钥,结果同样对不上。

排查时先问清楚最近有没有人重置或重新生成过密钥,再对一下两边保存的值是否相同,不要先怀疑算法写错。如果你们把密钥放在配置中心或环境变量里,还要确认生产实例已经完成了热更新或重启,避免配置页是新值、正在跑的进程仍是旧值。签名校验失败时,先不要关闭校验去「先通再说」,那会把未经验证的请求放进业务系统。

  1. 由保管密钥的人在美洽与接收方配置中各核对一次当前值,确认没有复制漏字符、没有把测试环境的密钥用到生产。核对过程中不要把密钥写进聊天记录或单据正文,以免扩散。
  2. 若确认已经轮换且两侧不一致,先把接收方改成与美洽当前密钥一致,再用一条测试对话看签名是否通过。不要在生产里临时关掉校验来验证通路,那会留下可被冒用的缺口。
美洽Webhook推送失败逐项检查步骤:核对接回调地址与密钥,再对照接收日志里的状态码

怎么从接收日志判断失败原因

官方说明里并没有单独描述「推送日志」或「失败记录」这样的固定界面,所以不要假定后台一定能列出每次推送的成败。判断依据要回到接收方:有没有接到请求、返回了什么状态码、有没有超时、证书握手是否失败。把这些和测试对话的发起时间对齐,原因会清楚很多。

状态码要这样看:只有返回 HTTP 200,美洽才视为本次推送成功;如果接口没有任何状态码返回,美洽也认为这次失败。返回 4xx,多半是路径不对、鉴权拒绝或签名校验没通过。返回 5xx,是接收服务自己出错,比如进程重启、依赖库崩溃、数据库写失败还把错误抛到了接口层。日志里出现连接超时、网关超时或证书验证失败,则要去查返回前是不是做了过重的逻辑,以及证书链是否完整。

  1. 按测试对话的精确时间,在访问日志里找到那一次请求,记下状态码、耗时和报错。找不到请求,就回到上一节的地址、端口、防火墙和证书,不要在代码里盲改。
  2. 状态码不是 200 时,先读这一次的错误堆栈或网关报错,区分是签名失败、路由找不到,还是程序异常。改完只重测这一类问题,避免把几个修复混在一次发布里。
  3. 耗时明显偏长或已经超时的,检查接口是否在返回前同步写库、调通知、打外部接口。这些都应放到返回成功之后再做,否则就算后面能处理完,美洽也已经按失败处理了。

对方服务:防火墙、证书、短暂出错和返回过慢

配置都对、日志里却完全没有请求时,就要看接收服务所在的环境有没有把来源拦在门外。防火墙、安全组、网关的访问控制,都可能在某次变更后不再放行美洽的推送。证书问题也很常见:证书过期、只配了站点证书却没带上中间证书,证书链不完整时,推送在握手阶段就会失败,接收应用日志里不一定看得到业务报错,要到网关或系统层的握手日志里查。

已经能打到接口、却时好时坏,重点看发布、重启和依赖波动。短暂的 5xx 往往出现在滚动发布、进程重启、数据库锁等待的那一两分钟。因为失败后暂无重试,这短短一两分钟里触发的「创建对话」可能已经丢了,不能指望过一会儿会自动再推一次。还有一种稳定复现的失败:接口在返回前做了过重逻辑,写库、呼叫下游、甚至同步发通知,拖过了可接受的等待时间,美洽收不到 200,就会判失败。

  1. 请负责网络的人确认,接收地址对应的端口和路径对外部推送是开放的,近期安全策略或放行名单有没有改动。若必须限制来源,把放行规则和实际入口对齐,改完立刻用测试对话验证,而不是只在内网用手动请求打通就结束。
  2. 检查当前证书是否在有效期内、完整链是否已安装到网关。链不完整时,浏览器有时还能打开页面,但程序之间的推送握手仍可能失败,不要只用浏览器能打开作为通过标准。
  3. 把接收接口改成先完成最小校验,确认是合法推送后尽快返回 200,再把写库和通知放到后台任务。这样即便后续处理变慢,也不会把一次本来能成功的推送拖成失败。

修好前先用工作台盯线,避免漏接待

既然失败后暂无重试,那么故障这段时间里没推成功的新对话,不会自动再送一遍。回调还没修好之前,值班人员要回到美洽工作台,盯新进入的对话和留言,按平时的接待流程处理,不能只守着业务系统的通知。工作台里能看到的对话,就是这段时间最可靠的底账;业务系统里缺失的,先以工作台为准来接待,而不是等推送恢复后再说。

盯线的同时并行修回调,不要把两件事串成「先修完再接待」。把开始收不到通知的大致时间记下来,方便后面在工作台按时间核对应接而未进业务系统的对话。修好之后,这些已经发生过的事件也不会因为你点了保存就自动补推,后面如何把漏掉的记录补进业务系统,放到常见问题里说明。

  1. 在工作台会话列表里按时间查看故障开始之后的新对话,确认每条都有人在接待,不要只看业务系统有没有弹通知。离线留言也要一并查看,避免只盯进行中的会话而漏了留言箱。
  2. 把「工作台有、业务系统无」的对话编号和时间记成一张临时清单,既方便值班交接,也为后面补数提供范围,避免恢复之后凭记忆补录,造成重复建档或漏补。
美洽Webhook排障要点:失败暂无重试,修好前用工作台盯新对话,再用测试对话验收

修好后用测试对话验收,并做对照

配置或接口改完,必须以一条真实触发「创建对话」的测试对话来验收,不能只看设置页保存成功。用测试渠道或测试访客发起新对话,确认接收日志里出现请求、状态码为 200,并且业务系统已经按预期落库或发出了内部通知。只有日志里有请求、库里也有记录,才能说这条链路重新通了。

同时做一条对照:触发一个你并未订阅的主题,例如你没有勾选「结束对话」,就正常结束这条测试对话,业务系统不应为此再写入一条「新对话」。对照的目的是避免把偶发成功、或把错误的事件类型当成验收通过。若你订阅了多种主题,也可以额外测一次「结束对话」,但那只能证明结束事件通了,不能代替「创建对话」的验收。

  1. 验收前先告诉值班这是测试,避免被当成真实客户。对话发起后,同时看美洽工作台是否生成了新会话、接收日志是否在同一时间到达、业务系统里是否出现对应记录,三处对得上才算通过。
  2. 再用未订阅的事件做一次对照,确认系统不会把不该接收的主题写成新对话。若对照也意外写入了,说明处理器可能没有按主题分流,要先修正再宣布恢复。
  3. 验收通过后,让同事按同一份步骤再复验一遍,尤其要在生产环境走通,避免只在测试实例里看起来正常,一切正式流量又失败。

常见问题

为什么只有某类事件会失败

如果「结束对话」能进业务系统,「创建对话」却一直没有,先回头看勾选列表,是不是只订了结束类主题。反过来,新对话能进、结束或小结更新进不去,也可能是后面几个主题根本没勾选。还有一种情况:主题都勾了,但接收程序只写了其中一种事件的解析,其它主题一到就因为字段不同而报错,于是只有某一类看起来是失败的。

「更新对话」只会在客服修改对话小结时触发,并不是访客每说一句话都会推一次;「首次分配客服」也只在会话第一次分到客服时触发。用这两个主题去判断「有没有新对话」,会漏掉尚未分配或还没写小结的会话。若失败只出现在某条渠道或某个时段,还要看接收方是否对特定字段做了必填校验,例如小结为空时直接抛错返回 5xx,这类问题不会表现成「所有推送都失败」。

失败后暂无重试,漏掉的对话怎么补

官方明确失败后暂无重试机制,所以不要在后台里找「重试队列」或「一键补推」之类尚未核实的按钮。这一次没成功的推送,可能已经丢了。漏掉的对话能不能再从官方侧查询或补拉,以官方是否提供查询或补拉能力为准;没有这类能力时,就回到工作台,按故障时间段把相关新对话逐条核对,必要时在业务系统里手工补录接待结果,而不能等待自动补送。

补数时以工作台里实际存在的会话为准,先覆盖故障开始到修复验收通过之间的时间窗。能对上的记录就补上业务侧的编号和状态,对不上的再单独登记,避免重复建档。修好后的测试对话只能证明新的推送已经恢复,不会把已经丢掉的那一批自动补回来,这两件事要分开看。

收不到美洽新对话推送时,按「先核地址、密钥和创建对话事件,再看接收日志里的请求和状态码,然后处理防火墙、证书和返回过慢,修好前用工作台盯线,最后用测试对话加对照事件验收」这一条路径走完,原因通常能定位到具体的一层。失败暂无重试,所以排障和盯线要同时进行,不要把接待完全押在这一条推送上。