上周有个朋友找我帮忙说在企业微信后台配应用消息回调点保存就一直报URL验证失败问我到底应该填什么。我把他的配置截图拿来一看URL填的是内网IP那当然过不去。后来帮他把服务部署到公网机器上重新设置Token和EncodingAESKey十分钟就通过了。这个事其实不难但接收消息服务器URL确实是很多刚接触企业微信消息推送的人第一个被劝退的坎。这篇文章是企业微信消息推送系列的第一篇我打算把接收消息这半边讲透。你会弄明白URL到底是干什么的、Token和EncodingAESKey是怎么参与验证的、第一次URL握手时服务器端要做什么、验证通过之后怎么接到第一条真实消息。不管你是要做一个内部工具应用还是想把企业微信消息接到自己的业务系统甚至后续要接智能对话机器人第一步都要把URL调通。1. 接收消息服务器URL到底解决什么问题1.1 自建应用的消息从哪里来、到哪里去在企业微信里创建一个自建应用后员工可以在应用里发消息、点菜单、上报地理位置、甚至是进入应用本身这些行为都会触发事件。企业微信服务器需要把这些事件和消息告诉应用开发者自己的服务器怎么告诉呢就是向开发者配置的URL发起HTTP请求。所以说URL其实就是一个回调地址。企业微信服务器是客户端你的服务器是服务端。员工在企业微信里做了一些操作企业微信后台替员工把操作内容打包成一个HTTP请求发送到你配置好的那个URL上。你的服务收到之后按格式解析再决定做什么业务。这个模型和微信公众号的消息推送基本一致但有个重要区别微信公众号用的是signature字段企业微信用的是msg_signature字段。很多人拿公众号的代码改一改就上结果在URL验证那一步就挂掉了因为参数名都不对。1.2 为什么需要一个公网可达的回调地址企业微信服务器是一套云端的服务它要主动访问你的业务服务器前提是你的业务服务器必须能被公网访问到。这就是为什么内网IP不行192.168.x.x、10.x.x.x、127.0.0.1全都过不了后台校验。一个合格的URL通常长这样https://yourdomain.com/wechat/callback路径可以自己定义不固定。但域名必须是公网可达的而且服务器要能处理来自企业微信服务器的请求。如果用的是云服务器那还要把对应端口在安全组/防火墙里打开。如果用的是公司内网服务器就得通过公网映射方式暴露出来。这就引入了很多部署上的问题。我在实际项目里见过不少开发者的第一版服务都是跑在自己笔记本上的用内网穿透临时调试。这个没问题但做生产环境时一定要切换到正式的域名和HTTPS。1.3 消息推送是推不是拉有些从零开始的朋友会问为什么不让我轮询企业微信接口自己去拉消息这就要说清楚企业微信的设计思路消息回调是推(push)模式不是拉(pull)模式。企业微信服务端在消息产生后会主动把数据POST到你的回调URL。这样一来你的服务端必须一直在线、稳定响应不能只在需要的时候才去调接口。也就是从你配置好URL那一刻起你的服务器就是一个常驻服务要随时准备接收请求。推模式的好处是实时性高消息发生后几百毫秒内就能到达业务服务器不需要频繁去轮询API。代价就是你的服务必须是公网可达的而且要考虑并发和断电恢复的问题。2. 配置前需要准备哪些东西2.1 前置条件清单在后台动手配置之前先把这些准备好。我列了一个清单每项都说明用途前置条件用途说明一个已认证的企业微信创建自建应用企业微信管理员账号自建应用接收消息和调用API管理后台-应用管理-自建公网服务器部署回调服务有公网IP/域名Linux/Windows均可开放端口让企业微信服务器能访问HTTP默认80HTTPS默认443URL回调地址必须以http://或https://开头Token签名校验参数自己设置的随机字符串EncodingAESKey消息加解密密钥后台可自动生成43位CorpID企业身份标识我的企业-企业信息里查看这里要特别强调一下接收消息本身只需要URL、Token、EncodingAESKey和CorpID。AgentId和Secret在后续主动调用发送应用消息接口的时候才会用到但建议现在就准备好后面跑通消息闭环时省得再回后台翻。2.2 内网穿透这类临时方案的取舍如果你只是在开发环境做联调本地起一个服务然后用内网穿透工具把公网地址映射到本地端口这完全可以。常见的工具包括ngrok、frp、natapp等选一个顺手就行。我自己在开发阶段经常直接用ngrok一条命令就能把本地8080端口暴露成临时域名。但必须提醒一句内网穿透只适合开发联调不适合生产环境。原因有三个临时域名不稳定可能隔一段时间就变延迟和带宽没有保障回调高峰期容易丢请求企业微信对回调域名有稳定性要求频繁变动会导致服务不可用。生产环境我建议用正式域名并配置有效的HTTPS证书。虽然企业微信允许填http地址但为了数据安全还是强烈建议用https。特别是消息内容可能涉及内部沟通信息明文传输风险太大了。2.3 需要理解的三个核心参数URL、Token、EncodingAESKey这三个参数是配置回调时手填的核心项必须理解它们各自的职责。URL是我们已经反复说的回调地址它是请求入口。Token是签名密钥它的作用是让服务器能够验证这个请求确实来自企业微信而不是某个恶意第三方伪造的。EncodingAESKey则是消息体加解密密钥它决定了对POST过来消息体进行AES解密的密钥是什么。很多人把Token和EncodingAESKey混为一谈觉得都是密钥其实分工完全不同。Token参与的是SHA1签名运算它不负责加解密EncodingAESKey参与的是AES-256-CBC加解密它不参与签名运算。两者缺一不可。EncodingAESKey的格式是固定的43位字符由大小写字母、数字组成。后台默认有一个随机生成按钮建议直接用。如果你要自己生成也要保证格式正确否则保存时会报错。另外这个EncodingAESKey不能随意更改一旦在后台改了你服务器里的解密密钥也必须同步改否则后续消息都无法正常解密。3. 第一次握手URL验证的完整过程3.1 企业微信发送的GET验证请求长什么样当你点击后台保存按钮的那一刻企业微信服务器立刻会往你填的URL发送一条HTTP GET请求。这个请求不是来拿效果的而是一次验证握手。只有你的服务器正确响应后台才会认定URL可用并保存成功。GET请求携带的参数有四个msg_signature: 签名值 timestamp: 时间戳 nonce: 随机数 echostr: 加密字符串请求URL长这样https://yourdomain.com/wechat/callback? msg_signaturexxxxtimestamp1234567890nonceabc123echostrabcdef...echostr虽然名字里带个str但它不是明文而是一段经过AES加密后的密文。你的服务器需要做两件事第一步验证签名第二步解密echostr把解密后的明文直接作为HTTP响应体返回。注意响应内容必须是纯文本明文不要加引号、不要包一层JSON、不要加换行。很多人在这一步栽跟头返回了{message:ok}或者返回了一个加密后的字符串企业微信全都判定为验证失败。3.2 签名校验逻辑和算法签名校验的目的是确认请求确实来自企业微信。如果那段echostr是别人伪造的签名就一定对不上。校验逻辑并不复杂一共四步将Token、timestamp、nonce、echostr四个字符串放进一个数组按字典序从小到大排序将排序后的数组拼接成一个字符串对拼接结果做SHA1哈希得到40位小写十六进制字符串与msg_signature对比。如果一致说明请求合法如果不一致直接拒绝。代码实现里唯一要注意的是参与排序和拼接的是原始的echostr不是解密后的明文。这点和后续POST消息验证签名时的逻辑完全一致参与签名的一律是加密后的密文。3.3 解密echostr并返回明文解密echostr的算法是企业微信的AES加解密方案核心是AES-256-CBC。你可能没有接触过这个协议但理解要点就够了。EncodingAESKey本身是一串43位可见字符对它加上一个等号然后做Base64解码得到32字节的AES密钥。IV初始向量取这个32字节密钥的前16字节。解密时采用PKCS7填充方式。解密后的数据格式是固定的前16字节是随机字符串紧接着4字节是网络字节序的消息长度再往后就是真正的消息内容最后是CorpID。在URL验证场景中你不需要关心前16字节和后面CorpID只需要取出中间的消息长度区间内的内容把它作为明文返回即可。3.4 用Flask实现URL验证的完整代码我平时用Python比较多就以Flask为例给出一段可以跑通的URL验证代码。如果你用Java或Node.js核心逻辑也是一样的可以照搬签名和AES部分。先实现加解密类。为了让你看懂每一段在干什么我没有依赖企业微信官方库而是直接用pycryptodome这个常见的AES库。实际项目中你也可以用官方提供的WXBizMsgCrypt类思路完全一致。import base64 import hashlib import socket import struct from Crypto.Cipher import AES class WXBizMsgCrypt: def __init__(self, token, encoding_aes_key, receive_id): self.token token self.key base64.b64decode(encoding_aes_key ) self.iv self.key[:16] self.receive_id receive_id def verify_url(self, msg_signature, timestamp, nonce, echostr): # 1. 校验签名 if self._get_signature(timestamp, nonce, echostr) ! msg_signature: raise Exception(signature error) # 2. 解密echostr return self._decrypt(echostr) def _get_signature(self, timestamp, nonce, encrypt): sort_list sorted([self.token, timestamp, nonce, encrypt]) content .join(sort_list) return hashlib.sha1(content.encode(utf-8)).hexdigest() def _decrypt(self, encrypted): cipher AES.new(self.key, AES.MODE_CBC, self.iv) pad_text cipher.decrypt(base64.b64decode(encrypted)) pad_len pad_text[-1] content pad_text[:-pad_len] # 16字节随机串 4字节消息长度 消息体 receiveId msg_len socket.ntohl(struct.unpack(I, content[16:20])[0]) msg content[20:20 msg_len].decode(utf-8) return msg代码里的_decrypt方法去掉了对receive_id的严格校验。生产环境建议保留校验判断解密后的消息尾部是否和当前CorpID一致能多一层安全保障。然后实现Flask路由from flask import Flask, request app Flask(__name__) TOKEN 你的Token ENCODING_AES_KEY 你的EncodingAESKey CORP_ID 你的CorpID app.route(/wechat/callback, methods[GET]) def verify_url(): msg_signature request.args.get(msg_signature) timestamp request.args.get(timestamp) nonce request.args.get(nonce) echostr request.args.get(echostr) crypt WXBizMsgCrypt(TOKEN, ENCODING_AES_KEY, CORP_ID) try: ret crypt.verify_url(msg_signature, timestamp, nonce, echostr) return ret except Exception as e: # 这里一定不要返回200让企业微信知道验证失败 return verify fail, 403 if __name__ __main__: app.run(host0.0.0.0, port80)把这段代码部署到公网服务器并运行后再在企业微信后台填好URL、Token和EncodingAESKey点击保存。正常情况下后台会提示保存成功。有一个小细节容易坑人如果你用的服务器上80端口被占用了可以换成8080等端口URL里也要把端口写清楚比如http://yourdomain.com:8080/wechat/callback。企业微信并不会强制只用80或443只要URL能访问到就行。4. 验证通过之后怎么接收真实消息4.1 POST回调的消息体和加密格式URL验证通过这只是一个开始。真正有消息产生时企业微信服务器会向同一个URL发送HTTP POST请求。GET和POST共用同一个回调地址你的路由必须同时处理两种方法。POST请求的Query参数和GET验证时一样包含msg_signature、timestamp、nonce三个字段但请求体不再是echostr而是一段XML。如果你在后台选择的是安全模式推荐请求体长这样xml ToUserName![CDATA[corpid]]/ToUserName Encrypt![CDATA[密文内容]]/Encrypt AgentID![CDATA[agentid]]/AgentID /xml收到POST请求后你需要做三件事用Query里的timestamp、nonce和Body里的Encrypt字段重新计算签名比对msg_signature确认合法然后对Encrypt字段做AES解密最后得到真正的明文消息XML。这里一定要记住计算签名时参数里的encrypt取的是Body里Encrypt标签的内容而不是整个XML原文。这个细节我和同事联调时踩过坑用整段XML去算哈希结果校验永远不过。4.2 消息类型与事件的区分解密后得到的明文XML不同消息类型有不同的结构。最基础的是文本消息xml ToUserName![CDATA[corpid]]/ToUserName FromUserName![CDATA[userid]]/FromUserName CreateTime1234567890/CreateTime MsgType![CDATA[text]]/MsgType Content![CDATA[你好]]/Content MsgId1234567890/MsgId AgentID1000002/AgentID /xml其中FromUserName是员工的UserIDContent是消息内容MsgId是这条消息的唯一ID可以用来做幂等处理。除了text之外还有image、voice、video、location等消息类型以及事件类型event。常见事件包括MsgTypeEvent说明evententer_agent成员进入应用eventlocation上报地理位置eventtemplate_card_event模板卡片事件eventsubscribe成员关注应用实际项目中我遇到过很多需求本质上是员工在应用里点了一个按钮希望服务器收到通知。这种需求往往就是通过回调事件实现的。所以解析时不要只处理text要把MsgType和Event字段都考虑进去。4.3 如何安全地处理和响应企业微信服务器在POST请求发出后会等待你的服务器返回结果。如果成功收到HTTP 200响应且响应不为空它会认为你已经处理完毕。但如果你超过5秒没有响应或者响应不是200企业微信会认为发送失败并重试多次。这就带来一个设计上的重要原则回调接口里别做耗时操作。我见过有人直接在回调里调用外部接口做智能问答一个请求要花十几秒才返回结果企业微信一直在重试导致消息重复处理。正确做法是把消息先解析出来丢进消息队列或后台任务然后立刻返回200或空串。响应策略有两种被动回复在5秒内直接返回一个xml响应给用户主动发送回调接口先返回空串之后用发送应用消息API主动给用户推送。两种方式可以配合使用。如果是需要复杂业务处理的场景我推荐第二种用消息队列异步处理用户体验更好。5. 实测中容易踩的坑5.1 验证失败的典型原因排查我帮别人排查URL验证失败时基本按下面这个顺序查建议你也可以按这个思路走URL能访问吗先用浏览器直接访问你的URL看看是否有响应。如果浏览器都打不开企业微信肯定也打不开。防火墙和安全组开端口了吗云服务器只开系统防火墙还不够安全组也要检查。后台填的Token和服务器代码里的Token一致吗最容易犯的低级错误校对三遍都不嫌多。参数名真的写对了吗确认是msg_signature不是signature。解密返回的是明文吗在验证接口里返回的必须是解密后的明文绝不能把echostr原样返回。HTTP状态码是不是200验证失败时如果直接返回403企业微信会立刻判定失败。如果以上都查过还是不行建议在服务器上临时写一个打印函数把收到的所有参数原样打印到日志里然后手动模拟一次验证请求。这样能快速发现是签名不匹配还是解密报错。5.2 Linux/信创环境下部署的注意点接收消息服务本质上是一个HTTP服务和操作系统关系不大。不管你是用Ubuntu、CentOS还是麒麟这类国产系统只要Python环境能装上依赖代码就能跑。在Linux服务器上部署的常规步骤是pip install flask pycryptodome python app.py生产环境更建议用gunicorn或uwsgi做进程管理配合systemd设置开机自启。简单写一个systemd服务文件就能保证回调服务在服务器重启后自动拉起。在信创环境下偶尔会遇到pip源没法访问的问题。解决办法是提前在可联网的机器上把依赖包下载成whl文件再拷贝到内网/信创环境里离线安装。还有一点要注意某些老旧系统自带的Python版本可能是3.6或更低而pycryptodome需要较新的Python版本事先确认好兼容性。5.3 调试工具和日志技巧我在调试企业微信回调时最常用的工具是以下几类内网穿透工具ngrok、natapp本地开发时快速暴露服务Postman/Apifox手动构造GET验证请求和POST消息请求系统日志每次回调都打印时间、参数、body、处理结果方便回溯。有个非常实用的技巧在回调接口入口先不要加任何业务逻辑把整条请求完整地打印出来。比如这样app.route(/wechat/callback, methods[GET, POST]) def callback(): print(method:, request.method) print(args:, request.args) if request.method POST: print(body:, request.get_data(as_textTrue)) return ok这样能先搞清楚企业微信到底发了什么、参数长什么样、Body格式对不对。确认没问题之后再往里面加签名校验和解密逻辑。别看这个操作简单它至少能省掉你一半的排查时间。6. 往后怎么玩从接收消息到智能应用6.1 被动响应与主动发送的配合把接收消息跑通之后你会发现企业微信消息推送的基本盘已经稳了。接下来要思考的是怎么让消息活起来。最直接的玩法是做一个聊天机器人员工在企业微信里给应用发一条消息你的回调接口收到后解析文本返回一段智能回复。这一步又回到我们前面说的两种响应方式。如果只是简单关键词匹配用被动回复就够了直接在回调里构造XML返回如果后面要接大模型、接企业知识库那最好用异步方式先回空串再用发送消息API把最终结果推给用户。主动发送消息API是另一个独立体系它不需要回调URL也能工作只需要CorpID、Secret和AgentId然后把内容POST到企业微信接口。但回调接收是它最好的搭档回调负责收主动发送负责回正好形成一个闭环。6.2 与机器人、DeepSeek等场景结合最近不少人问企业微信能不能接入DeepSeek这类大模型做智能客服答案是当然可以。前提就是先把接收消息这关过了。回调收到员工消息后把文本转发给大模型接口拿到回复再通过发送消息API推回给员工。整个链路看着复杂但主干就是我们这篇文章里搭好的回调服务。类似的还有把企业微信消息转发到Webhook、对接金蝶云这类业务系统、在Linux/信创机器上做自动化运维通知。不管哪种玩法第一步无一例外都是先把URL验证通过把消息接收能力准备好。这也是我为什么把这篇作为系列第一期的原因。后面的文章我会继续展开消息加解密的完整代码、主动发送消息API、被动回复的XML格式、以及如何结合大模型做智能对话。你可以先把这篇文章里的URL验证代码跑通有了稳定回调后面的内容才谈得上实操。6.3 部署建议和安全建议最后给你几条来自实战的安全建议Token和EncodingAESKey别硬编码。至少放到环境变量或配置中心里别提交到Git仓库。主动发送消息API调用前一定要在后台配置可信IP。否则接口会报IP不在白名单内。回调接口统一做异常兜底。不能因为某个消息解析失败就让整个服务崩溃异常时要记录日志并返回非200触发企业微信重试机制。定期更换EncodingAESKey但更换前要确保服务器已同步否则中间会有一段消息解密失败的空窗期。回调接口最好做独立进程部署和核心业务隔离因为企业微信回调的流量特性是突发式的高并发独立进程能避免拖垮其他服务。我实际跑过一段时间后发现企业微信回调稳定性整体不错偶尔会有重复推送或延迟所以消息处理逻辑里一定要利用MsgId做幂等。同一个MsgId重复处理两次轻则业务数据重复重则给用户连发多条消息那个体验就很糟糕了。