签名验证失败是企微回调接入里出现频率最高的问题没有之一。这篇把我自己踩过的坑和排查方法整理出来按概率从高到低排。坑一密钥用错了这是最常见的原因占签名失败的一半以上。企微回调验签用的是签名密钥不是 App Token也不是 appid。三者在控制台里是不同的字段长得也不一样App Tokeneyk_xxxx用于 API 调用鉴权签名密钥一串随机字符串用于回调验签appidwe_xxx实例标识很多人把 App Token 当成签名密钥用算出来的签名当然对不上。去控制台确认一下你用的是不是回调配置里的那个密钥。坑二请求体被读过一次这是第二常见的原因而且特别隐蔽。很多 Web 框架在中间件里已经反序列化过 body业务代码再读request.body拿到的是空字节流。空 body 算出来的签名和收到的签名当然不一样。Spring BootRequestBody已经读过一次再用request.getInputStream()是空的。解决办法是用ContentCachingRequestWrapper或者自定义 filter 提前缓存。Flaskrequest.get_data()和request.json都会消费 body。解决办法是用request.get_data(cacheTrue)或者自己存一份。Expressbody-parser已经解析过再用req.body是对象不是原始字节。解决办法是用express.raw()或者自己实现 raw body 中间件。# Flask 正确做法 app.route(/wx-api/webhook/, methods[POST]) def webhook(): raw_body request.get_data(cacheTrue) # 先拿原始字节 signature request.headers.get(X-Eyun-Signature) expected hmac.new( SECRET.encode(), raw_body, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(expected, signature): return forbidden, 403 data request.get_json() # 再解析 JSON # ...坑三编码不一致报文里有中文验签的字节编码必须和发送方一致。企微回调用 UTF-8 编码。如果你的服务在接收时按 GBK 或其他编码转了一次字节流就变了签名自然对不上。检查点服务器默认编码是不是 UTF-8框架有没有自动转码中间件有没有做字符集转换# 确保按 UTF-8 取字节 raw_body request.get_data(cacheTrue) # 不要这样做raw_body request.get_data().decode(gbk).encode(utf-8)坑四header 大小写问题HTTP header 名是大小写不敏感的但不同框架、不同语言的取值方式不一样。X-Eyun-Signature和x-eyun-signature是同一个 header但有的框架里request.headers.get(X-Eyun-Signature)能拿到request.headers.get(x-eyun-signature)拿不到排查时把 header 名打出来看看确认取到的是不是预期的值。# 打印所有 header确认签名 header 的名字 print(dict(request.headers))坑五echostr 验证和消息推送的混用配置回调地址时平台会发一个带echostr的验证请求要求你原样返回。这个请求不需要验签直接返回 echostr 就行。但很多人生成的验签逻辑对验证请求也跑了一遍结果签名对不上验证失败。app.route(/wx-api/webhook/, methods[POST, GET]) def webhook(): # 验证请求直接返回 echostr不验签 echostr request.args.get(echostr) or ( request.json.get(echostr) if request.is_json else None ) if echostr: return echostr # 消息推送验签 signature request.headers.get(X-Eyun-Signature) raw_body request.get_data(cacheTrue) expected hmac.new(SECRET.encode(), raw_body, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, signature): return forbidden, 403 # ...一套快速排查的顺序确认用的是签名密钥不是 App Token打日志收到的签名、算出来的签名、原始 body 的前 100 字节确认 body 没有被提前读过确认编码是 UTF-8确认 header 名大小写区分验证请求和消息推送按这个顺序走一般两三轮就能定位。签名验证失败不是玄学是输入不对。把输入打出来比对问题一目了然。签名密钥在 Eyun 控制台的实例配置里生成回调字段说明在Eyun 开发文档里能查到。
