在 SpringBoot 项目中接收企业微信消息，必须使用“企业自建应用”的回调模式，普通群机器人 webhook 仅支持发送消息。需要配置公网可访问的回调 URL 并完成 Token 验证与 AES 解密。

命令速用版

快速处理思路是引入企业微信 SDK 或手动实现 AES 解密，核心是编写一个同时支持 GET 和 POST 的 Controller 接口。

<dependency>
    <groupId>com.github.binarywang</groupId>
    <artifactId>weixin-java-cp</artifactId>
    <version>4.5.0</version>
</dependency>

若不使用 SDK，需自行实现 SHA1 签名验证与 AES 解密逻辑，参考企业微信官方加解密库。

为什么会这样

企业微信的消息接收机制依赖于回调 URL 的主动推送，而非客户端轮询。普通群机器人 webhook 设计为单向发送，不具备接收用户消息的权限通道。只有自建应用配置了回调 URL，企业微信服务器才会在收到用户消息时向该 URL 发起 HTTP POST 请求。

分步处理

第一步：企业微信后台配置

登录企业微信管理后台，进入“应用管理”创建自建应用。在“接收消息”设置中填写回调 URL、Token 和 EncodingAESKey。URL 必须是公网可访问地址，支持 80 或 443 端口。

第二步：SpringBoot 接口开发

编写 Controller 接口，路径需与后台配置的回调 URL 一致。接口需支持 GET 请求用于验证 URL 有效性，支持 POST 请求用于接收实际消息。

@RequestMapping("/wechat/callback")
public String handleWeChat(@RequestParam Map<String, String> params, @RequestBody String body) {
    // GET 请求验证签名
    // POST 请求解密消息体
    return "success";
}

第三步：处理加密消息

企业微信默认使用 AES 加密消息体。接收到的 POST 数据需使用配置的 EncodingAESKey 进行解密。解密失败或返回内容不包含 success 字符串，企业微信会判定接收失败并重试。

怎么验证是否生效

查看企业微信管理后台“接收消息”配置页，状态显示“正常”即表示 URL 验证通过。在 SpringBoot 应用日志中搜索接口访问记录，确认收到 POST 请求且解密后的 MsgType 字段符合预期。发送测试消息给应用，检查日志是否打印出明文内容。

常见坑

网络可达性问题：回调 URL 必须是公网 IP 或域名，本地 localhost 地址无法接收推送。若在内网测试，需使用内网穿透工具映射公网地址。

响应超时限制：企业微信等待接口响应的时间通常为 5 秒。若 SpringBoot 业务逻辑耗时过长，会导致重试或判定失败。建议收到消息后异步处理，先返回 success。

编码与签名错误：验证 GET 请求时需严格按文档顺序拼接参数并 SHA1 加密。字符编码需统一使用 UTF-8，否则签名校验无法通过。

常见问题

普通群机器人能接收消息吗？

不能。普通群机器人 webhook 仅支持向群内发送消息，接收消息必须使用自建应用回调模式。

接口返回什么内容才算成功？

接口必须原样返回加密前的 echostr 字符串（验证阶段）或返回明文 success 字符串（消息接收阶段），具体取决于请求类型。

收不到消息怎么办？

检查企业微信后台回调状态是否为“正常”，确认防火墙是否放行 80/443 端口，查看应用日志是否有请求进入但解密失败。

参考来源

企业微信开发者文档 - 接收消息事件：https://developer.work.weixin.qq.com/document/path/90235

企业微信开发者文档 - 回调模式：https://developer.work.weixin.qq.com/document/path/90235