企业微信标准群机器人 webhook 仅支持向外发送消息,不具备接收消息回调功能;若指的是自建应用回调 URL 签名验证失败,主要因 Token 配置不一致、签名算法参数排序错误或字符编码非 UTF-8 导致。
先说结论:签名验证失败通常是本地计算签名与企业微信发送签名不一致,需优先核对 Token 和算法逻辑。
- 先确认:检查后台配置的 Token 与代码中是否完全一致,区分大小写。
- 先处理:确保参数字符串按字典序排序后拼接,并使用 SHA1 算法。
- 再验证:通过日志对比本地生成签名与请求头中的 msg_signature 是否匹配。
命令速用版
若无现成代码,可用命令行快速验证 SHA1 逻辑,确认本地环境哈希计算是否正常。
echo -n "token12345678901234567890" | sha1sum
将 token、timestamp、nonce 拼接后测试,确认输出哈希值长度是否为 40 位十六进制。
为什么会这样
签名验证机制要求本地服务端复现企业微信的签名计算过程,任何细微差异都会导致校验不通过。
企业微信回调签名使用 SHA1 算法,将 Token、timestamp、nonce 三个参数按字典序(ASCII 码)排序后拼接成字符串进行哈希。若代码中参数顺序错误、Token 包含隐藏空格、或请求体编码非 UTF-8,计算出的签名值就会不同。此外,标准群机器人 webhook 地址仅用于接收 POST 请求发送消息,本身不触发签名验证流程,混淆功能场景也会导致配置无效。
分步处理
按以下顺序排查回调签名验证问题,每步完成后重试请求。
1. 核对 Token 配置
登录企业微信管理后台,进入应用设置页面,复制回调 URL 配置的 Token。检查代码中存储的 Token 字符串,确保无首尾空格,字符完全一致。
2. 检查签名算法逻辑
确认代码逻辑是将 token、timestamp、nonce 三个字符串按字典序(ASCII 码)排序,然后直接拼接,中间无分隔符。使用 SHA1 算法计算哈希,结果转为小写十六进制字符串。
3. 确认字符编码
确保接收到的请求参数和本地拼接字符串均使用 UTF-8 编码。部分语言默认编码可能不同,需显式指定编码格式进行哈希计算。
4. 验证 echostr 返回
在验证回调 URL 阶段,签名验证通过后,必须原样返回请求中的 echostr 参数,否则企业微信会判定验证失败。
怎么验证是否生效
在企业微信管理后台点击“验证 URL”按钮,若页面提示“验证成功”且本地日志收到请求,说明签名验证已生效。
查看服务端日志,打印接收到的 msg_signature 和本地计算的 signature,对比两者是否完全一致。若一致但仍失败,检查 HTTP 响应状态码是否为 200 且响应体内容符合要求。
常见坑
1. 功能混淆:群机器人 webhook 地址不能配置为应用回调 URL,两者用途不同。
2. 参数缺失:某些请求可能缺少 nonce 参数,需做空值处理或按文档要求补全。
3. 时间同步:服务器时间与企业微信服务器时间偏差过大可能导致 timestamp 校验失败,建议配置 NTP 同步。
4. 转义问题:URL 中的特殊字符未正确编码,导致接收到的参数值与发送时不一致。
常见问题
企业微信 webhook 机器人能接收消息吗?
标准群机器人 webhook 仅支持发送消息,不支持接收;若需接收消息需使用自建应用回调功能。
签名验证失败一定要改 Token 吗?
不一定,优先检查代码中的签名计算逻辑和参数拼接顺序,Token 不一致才需要修改。
SHA1 算法计算出的签名长度是多少?
SHA1 哈希值通常为 40 位十六进制字符串,需确保转换为小写且无多余字符。
参考来源
企业微信开发者文档 - 验证回调 URL https://developer.work.weixin.qq.com/document/path/90930
企业微信开发者文档 - 接收消息签名验证 https://developer.work.weixin.qq.com/document/path/90931