企业微信二次开发：回调签名校验在项目中的完整实现

上周五刚准备提包下班，一个做教培 SaaS 的技术负责人发来一张满屏 ERROR 的监控截图，语音里都带着颤音："老哥，我们系统刚才自动给 300 多个客户发送了'课程退款已受理'的通知！但我们业务库里根本没有这些退款动作啊，撞鬼了吗？"

我连进他们服务器，把 Webhook 接收层的代码拉出来一看，差点惊掉下巴。这帮哥们在对接初期，因为死活调不通加密算法，为了赶进度上线，直接把签名校验（Signature 验证）的代码全部注释掉了。只要是个带 JSON 的 HTTP POST 请求打过来，他们系统就照单全收。结果 Webhook 公网地址裸奔被扫描器扫到，被人拿假报文直接"投毒"，系统傻乎乎地全执行了。

作为每天在一线跟各种研发兄弟死磕微信及企微 API 接口（机器人）问题的销售客服，这种在"大门口"放弃安检的裸奔行为，我真是见一次心梗一次。今天咱们不聊业务，直接基于 星云API xingyapi.com 的底层安全规范，把企微最让人头疼的"签名校验与加解密"逻辑彻底打通，帮你把系统的防盗门焊死。

认知对齐：为什么非得搞这么复杂的签名？

很多人吐槽，别人家的 Webhook 直接推明文 JSON 多好，为啥企微非要搞什么 Token、EncodingAESKey，还得算 SHA1 签名？

答案很简单：防篡改 + 防伪造。公网环境是极其险恶的。如果没有签名校验：

黑客可以伪装成企微网关，向你的服务器发送虚假事件（比如伪造客户付款成功的回调）。
竞争对手可以截获报文，修改里面的 Content 再转发给你。

签名校验的本质，就是企微网关和你的服务器之间对的一次"接头暗号"。只有暗号对上了，你才能相信这串数据真的是官方推过来的。

第一道难关：GET 请求与 URL 有效性验证

所有接 Webhook 的研发，遇到的第一个下马威绝对是"保存回调地址"这一步。当你在后台配置好 URL 点击保存时，企微网关并不会给你发数据，而是会发起一个 HTTP GET 请求来测试你的接口。

这时的请求 URL 长这样： [http://api.yourdomain.com/webhook?msg_signature=3a7b...&timestamp=1400012345&nonce=1234&echostr=加密的随机字符串](http://api.yourdomain.com/webhook?msg_signature=3a7b...&timestamp=1400012345&nonce=1234&echostr=加密的随机字符串)

实战解密步骤：

验签（算暗号） ：把你在控制台设置的 Token、URL 里的 timestamp 和 nonce 这三个字符串放到一个数组里，进行字典序排序。然后拼接成一个长字符串，做一次 SHA1 哈希加密。
比对：把你算出来的哈希值，跟 URL 里的 msg_signature 对比。如果一模一样，证明请求确实来自官方。
解密返回 ：验证通过后，用你的 EncodingAESKey 对 echostr 进行 AES 解密。然后原样返回解密后的明文（必须是纯文本，不能带任何 JSON 或 HTML 标签）。

致命大坑 ：很多框架（比如 SpringBoot）的 @RestController 会默认给返回的字符串加上双引号，导致验证失败。一定要确保 HTTP 响应的 Content-Type 是 text/plain 且没有额外引号！

第二道难关：POST 请求与真实业务报文的防伪

URL 验证通过后，你的机器人就正式上线了。客户在群里发消息时，网关会向同一个 URL 发起 HTTP POST 请求。注意，这时候 URL 里的参数和 Body 里的东西全变了。

这时的请求长这样： URL 参数依然带有 msg_signature、timestamp、nonce。但 Body 里面是一段密文（XML 或 JSON 格式，星云API底层多采用 JSON 封装）。

实战防御三板斧（缺一不可）：

Java

复制代码

// 伪代码演示，严禁照抄，领会精神
String signature = request.getParameter("msg_signature");
String timestamp = request.getParameter("timestamp");
String nonce = request.getParameter("nonce");
String encryptData = extractEncryptDataFromBody(request.getBody()); // 从 Body 中提取密文字段

// 第一斧：防伪造（重新计算 SHA1）
// 注意！POST 验签时，参与排序哈希的，除了 Token、timestamp、nonce，还多了一个 Body 里的密文字段（encryptData）！
String mySignature = SHA1.getSHA1(Token, timestamp, nonce, encryptData);

if (!mySignature.equals(signature)) {
    // 签名不一致，绝对是黑客投毒，直接 HTTP 403 滚蛋，绝不往下走！
    throw new SecurityException("非法请求，签名校验失败！");
}

// 第二斧：防重放（缓存 Nonce 与 Timestamp）
// 记录请求的 timestamp，如果这个时间戳是半小时前的，说明这是黑客截获的过期报文在重放，直接丢弃。
if (Math.abs(currentTime - timestamp) > 300) {
    throw new SecurityException("报文已过期！");
}

// 第三斧：正式解密
// 安全校验全过了，这时候再用 EncodingAESKey 进行 AES解密，拿到真实的业务 JSON。
String plainText = AESDecrypt(encryptData, EncodingAESKey);

老司机的排障铁律：拿工具把算法"盘包浆"

加密解密（尤其是 AES 的 PKCS7 填充和 Base64 反解）是极其底层的操作，各种语言的底层库实现都有细微差别。如果直接在线上和真实的企微网关联调，每次报错你都不知道是密钥配错了、参数传少了、还是算法本身写劈了。

在碰业务代码前，先用工具把算法扒层皮！

把 Apifox 或者 Apipost 打开：

自己写个简单的脚本，用你知道的明文和密钥，算出一个合法的 msg_signature 和 encryptData。
在 Apifox 里，构造一个带签名的 GET 请求去打你本地的验证接口，确保能返回明文。
再构造一个带签名的 POST 请求去打你本地的接收接口，故意把 nonce 改错一个字母，看你的代码能不能精准拦截并报出"签名错误"。
在调试工具里把"合法放行、非法拦截"的边界测试得明明白白，再发到生产环境去接网关的真实流量。

加密校验这块的代码，写好一次直接封装成公司级的 Jar 包或者公共模块，以后接 100 个新项目直接复用，别每次都重新踩一遍 AES 乱码的坑。你们在搞加解密的时候，有没有遇到过某些特殊字符（比如 Emoji 或者全角标点）解密后被诡异截断的现象？赶紧去查查你们底层解析流的时候是不是把字符编码（UTF-8）给漏了。

架构安全无小事，下期咱们聊点轻松的：怎么给机器人加上"长连接"心跳检测，回见！