企业微信机器人消息收不到？Webhook排查

企业微信机器人消息收不到怎么办？先不要反复更换Webhook或连续补发。应把链路拆成四段：业务事件是否产生、通知任务是否执行、Webhook请求是否被企业微信接受、消息是否进入正确群聊。每一段都留下时间和结果，通常就能定位问题发生在哪一层。

企业微信当前官方文档把这项能力称为“自定义消息推送”，很多用户仍习惯称为群机器人或Webhook机器人。名称不同不影响排查方法。需要特别注意：Webhook地址相当于向群聊写入消息的凭证，不能发到公开群、截图、工单正文或代码仓库。

先用四个结果判断故障层级

检查结果	更可能的问题	下一步
后台没有对应业务记录	事件没有触发或记录失败	先查业务入口、时间和事件条件
有业务记录，没有通知任务	通知开关、规则或队列未执行	查任务创建日志和配置
已请求Webhook，返回非成功结果	地址、请求体、频率或网络问题	保存脱敏响应并按错误层排查
接口成功，群里仍找不到	群聊选错、查看范围或客户端定位问题	核对目标群和消息时间

如果机器人用于客户投诉提醒，后台投诉记录应作为事实来源，群通知只是加速响应的辅助通道。消息没出现时不要据此判断“没有投诉”，可先按企业微信客户投诉处理流程检查后台记录和待处理事项。

企业微信自定义消息推送与投诉提醒效果示例 — 自定义消息推送可以把业务提醒发送到指定企业微信群；排错时要同时核对后台事件、Webhook响应和实际目标群。

第一步：确认业务事件真的产生了

先找到一条明确的测试事件，记录事件编号、产生时间、业务账号和预期通知群。不要直接用模糊的“刚才好像没收到”排查，因为服务器、队列和手机显示时间可能存在差异。

事件是否满足通知条件，例如状态、类型或开关范围。
后台是否已经保存该事件，保存时间是否与测试一致。
同一事件是否被去重，之前是否已经标记为发送。
通知任务由同步请求、定时任务还是队列执行，执行进程是否正常。
失败任务是否有重试次数和最后错误，避免无限重复发送。

最有效的测试是“一条事件对应一个可追踪编号”。日志中只记录Webhook末尾的短指纹或配置编号，不要记录完整地址和key。

第二步：核对Webhook是否仍属于目标群

确认通知配置选中的地址来自当前目标群，创建者仍有权查看和管理该消息推送。群被更换、推送被删除后重建、复制时多了空格，或者测试环境覆盖了正式配置，都可能让业务端继续调用一条错误地址。

在企业微信目标群的消息推送详情中重新核对，不从聊天记录里翻旧地址。
检查地址首尾空格、换行和配置环境，确认正式环境没有使用测试群地址。
只比较脱敏后的配置指纹，不在多人屏幕共享中展示完整key。
如果怀疑Webhook曾公开或泄漏，应停用并重新创建，再更新业务端密钥。

玩创SaaS产品中企微客诉提醒的具体配置入口可查看企微客诉系统使用教程与效果演示。排错文章用于判断通知链路，不替代产品中的实际配置步骤。

第三步：从实际服务器发送最小测试消息

电脑上测试成功、服务器仍失败，通常说明问题在正式环境的DNS、HTTPS出口、代理、证书信任或配置加载。应从真正执行通知任务的服务器发送一条最小文本消息，并同时记录请求开始时间、耗时、HTTP状态和企业微信返回的JSON。

POST https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=REDACTED
Content-Type: application/json; charset=utf-8

{"msgtype":"text","text":{"content":"通知链路测试：TEST-ID"}}

示例中的key必须替换为保存在安全配置中的真实值，日志和截图仍应保持脱敏。不能只看HTTP连接是否成功，还要解析响应中的业务结果；若返回非成功结果，保留错误码、错误说明和测试编号即可，不保存完整Webhook。

第四步：检查JSON、编码和消息大小

企业微信官方文档要求向Webhook发送HTTPS POST，请求体使用对应消息类型的JSON，文本内容采用UTF-8。当前文档中，text内容最长不超过2048字节，markdown内容最长不超过4096字节；这里按字节而不是按中文字数计算。

msgtype与后面的对象名称一致，例如text对应text。
JSON引号、换行和反斜杠经过正确转义，没有多余逗号。
发送前按UTF-8字节数检查长度，长告警只保留摘要和安全的详情链接。
变量为空时仍生成合法结构，不把数组、对象直接拼进字符串。
链接不携带密码、登录态、完整手机号或可复用签名。

排查消息中的详情链接打不开时，应把通知发送问题和页面访问问题分开。后者可使用微信跳转链接分层排查清单检查HTTPS、重定向和目标页。

第五步：检查频率和重试策略

企业微信官方文档当前说明，每个自定义消息推送发送的消息不能超过20条/分钟。短时间大量事件逐条发送，可能触发频率限制；失败后立即高并发重试，又会让问题持续。

相同类型告警在短窗口内合并数量和时间范围。
每个业务事件设置幂等编号，避免队列重启后重复通知。
可重试错误采用递增等待，并设置最大次数。
配置最终失败队列和人工查看入口，不静默丢弃。
监控一分钟发送量、成功结果、失败类型和积压数量。

不要为了“实时”让每次页面访问都直接调用Webhook。先把业务记录可靠保存，再由受控任务发送通知，既方便重试，也能防止用户刷新页面造成重复消息。

接口成功后，为什么群里还看不到

先按测试编号和发送时间在目标群查找，而不是只看手机通知栏。核对Webhook对应的群是否正确、群成员查看的是否为同一企业身份，以及消息是否被大量提醒淹没。若需要提醒指定成员，还要分别验证消息是否送达和@对象是否正确，这两个结果不能混为一个。

生产环境还应保留一条独立的“通知通道健康检查”，但不要用高频空消息测试。可以定期发送带测试编号的低频消息，并结合域名与HTTPS状态监测方法检查服务器到Webhook域名的基础连通性。

适合长期保留的通知日志

字段	建议记录	不应记录
业务关联	事件编号、类型、产生时间	与排错无关的完整客户资料
通道标识	内部配置ID或Webhook短指纹	完整Webhook和key
请求结果	时间、耗时、HTTP状态、错误码	含敏感参数的完整请求
重试	次数、下次时间、最终状态	无上限的即时重试记录
处理闭环	责任人、处理结论、恢复时间	只写“已解决”没有依据