排查钉钉机器人收不到消息,我一般先不问“为什么丢了”,而是先确认“发送端到底得到了什么结果”。很多问题并不是消息真的没发出去,而是发送方误以为已经成功。不同阶段确认的东西不一样,处理顺序对了,能少走很多弯路。
从发送返回码开始判断
当钉钉机器人偶尔收不到消息时,首先需要确认消息发送接口的返回码。钉钉开放平台的Webhook接口在调用成功时会返回HTTP 200和errcode为0的JSON响应。如果返回非零errcode,比如errcode为310000或310001,通常对应签名错误或关键词不匹配。这里的关键在于,很多开发者在发送消息时只检查了HTTP状态码,没有检查响应体中的errcode,导致被频率限制或签名错误的问题掩盖。建议在发送逻辑中记录完整的响应内容,以便区分是网络抖动、接口限制还是配置问题。
我遇到过一个案例:本地测试时消息正常,部署到服务器后偶尔丢失。最后发现是服务器上发送代码只判断了HTTP 200,没有解析返回体,而实际响应里已经给出了errcode为310000的签名错误提示。所以,任何一次发送都应当把响应体完整打出来,至少保留最近几十条发送日志。
容易被误判的时间戳与签名
一个容易被忽略的问题是时间戳和签名的校验。钉钉自定义机器人支持加签安全设置,需要将时间戳和密钥拼接后计算HMAC-SHA1签名。如果服务器与钉钉服务器的时间偏差较大,即使签名算法正确也可能被拒绝。很多开发者在测试时用本机时间,部署到云服务器后忘记校准时间,导致偶尔出现签名验证失败。排查时可以在发送逻辑中打印系统当前时间,与钉钉服务器时间进行对比,误差超过1分钟就需要同步系统时间。另外,如果使用关键词安全设置,消息内容必须包含完整的关键词,而不是部分匹配。
这种问题最容易伪装成“偶尔丢消息”,因为时间偏移是持续的,但消息内容不同可能有时碰巧命中关键词或签名有效期,时好时坏。建议在服务器上执行date -u查看当前时间,再用钉钉接口报错里的时间字段做对比。如果发现系统时间有偏差,先启用NTP同步,再观察一段时间。不要只改代码里的签名逻辑,因为根因不在代码。
Webhook 使用上的限制与共享风险
排查机器人消息丢失时,建议先检查Webhook地址是否唯一且未被泄露。钉钉机器人每个自定义关键词或加签方式都对应一个独立的Webhook地址,如果同一个地址被多个服务同时使用,可能会触发消息限流。保守的做法是为每个业务场景单独创建一个机器人,避免共享Webhook。同时,确认消息发送时使用的HTTP客户端是否设置了合理的超时时间,建议连接超时和读取超时都设置在3秒以上,因为钉钉接口在高峰期可能出现响应慢的情况。超时过短可能导致请求被客户端主动取消,而服务端实际已收到消息。
Webhook地址泄露这件事,很多团队没有意识。如果某个机器人地址被写在公开文档或前端代码里,其他人也可能往里推消息,这样你自己的业务消息就会被挤掉。建议把Webhook当成密钥管理,如果不确定是否泄露,直接重置机器人的加签密钥,同时换一个新的Webhook地址。
超时设置也有讲究。有些HTTP客户端默认连接超时很长,但读取超时很短。当钉钉接口响应超过预期时间,客户端先断开,但服务端可能已经接受了消息,于是界面不显示。另一种情况是客户端设置了过短的总超时,比如1秒,网络稍微一抖动就失败。先看日志里有没有超时异常,再决定调整策略。
对频率限制要有保守预期
需要对钉钉机器人的频率限制有保守预期。官方并未公开精确的每分钟调用次数上限,但实际使用中,连续高频发送或短时间内大量并发可能导致部分消息被静默丢弃,不会返回错误码。因此,在业务高峰期或批量通知场景下,建议在发送端引入重试队列和退避机制,比如失败后等待100毫秒再重试,最多重试3次。同时,避免对同一Webhook地址发送超过每分钟20次请求,这是社区实践中普遍认可的保守阈值。如果业务需要更高吞吐,应申请企业机器人或使用群会话接口。
这里要特别注意:重试队列不能无脑重试。如果返回的是错误码,先判断错误类型;如果是限流或网络超时,可以重试;如果是签名错误或关键词不匹配,重试也没用,应该报警让维护者处理。另外,重试要加退避,否则所有重试请求挤在一起,反而加剧限流。
消息内容与群设置导致的“假丢失”
从问题现象入手,先区分是发送端失败还是接收端未展示。可以在发送消息时打印时间戳和消息ID,然后在钉钉群里查看消息是否到达。如果发送返回成功但钉钉未展示,需要确认机器人是否被群主设置了消息免打扰,或者群内是否存在同名机器人导致消息被过滤。另一种常见情况是:机器人发送消息的文本内容如果包含“@”符号,可能触发钉钉的@识别机制,导致消息格式异常而无法显示。此时可以尝试改用Markdown格式,或对内容中的特殊字符进行转义。
还有一类是消息被群合并或折叠。钉钉群内消息太多时,新消息可能被收纳到“折叠会话”里。这不是机器人问题,但容易被误认为消息丢失。所以,机器人发送完消息后,最好在代码里做一次显式的确认:把发送内容写入本地日志,再人工去群里搜索同一关键字。如果代码日志有内容、返回码为0、群里搜不到,再继续往下查。
验证与后续维护顺序
验证消息是否真正送达,可以在机器人发送成功后,到钉钉群的消息记录里搜索发送内容的关键字。但钉钉移动端和PC端的消息同步有时存在延迟,通常不会超过30秒。如果长时间不显示,可以用另一个机器人向该群发送测试消息,确认群本身的消息通道正常。另外,检查服务端日志中是否有发送异常的记录,包括网络超时、SSL验证失败、DNS解析错误等。如果日志中没有任何异常,而消息仍然丢失,需要考虑是不是钉钉服务端偶发故障,此时可以从钉钉开放平台公告中确认是否有相关事故通知,但不要依赖主观猜测。
整体处理顺序建议是先看返回码,再对服务器时间,然后检查Webhook唯一性、超时设置和频率模型,最后再考虑群设置和消息内容。每一步都需要确认:操作之后,下一次发送是否恢复正常。如果改了时间同步,就观察几小时内的发送成功率;如果换了新Webhook,就确认所有调用方都更新了地址。不要一次性改多个配置,否则问题消失后你也不知道是哪个改动起的作用。
后续维护上,建议给机器人发送逻辑加一个简单的监控:记录每分钟发送条数,连续发送失败时给运维群推一条告警。这个告警本身可以用另一个独立的机器人来发,避免业务机器人故障时告警也发不出去。只要保留完整日志,偶尔丢消息其实不难定位。