一个消息回调的设计哲学：论个人微信 API 的 Webhook 钩子怎么用才不踩坑
收到消息不做排重？回调里同步调 AI？6 秒超时不返回？——我在接入微信 API 的 Webhook 时踩过的坑，都写在这了。
前言：一个真实的需求
去年接了一个项目，需求很简单：把客户的个人微信变成 AI 客服，自动回复消息。
听起来不难是吧？API 发消息、收消息，两个接口的事。结果 Webhook 上线第一天，甲方的微信里同一个问题被 AI 回了五遍——因为断线重连触发了重复推送。
所以这篇文章不谈业务，就聊一件事：怎么做才算接对了 Webhook。
一、先理解：回调在整个系统里的位置
┌──────────┐ HTTP POST ┌──────────┐ WebSocket ┌────────┐ │ 你的服务 │ ←──────────── │ 开放平台 │ ←─────────── │ 微信 │ │ │ │ │ │ │ │ 你的服务 │ ─────────────→│ 开放平台 │ ─────────────→│ 微信 │ └──────────┘ HTTP POST └──────────┘ HTTP API └────────┘看懂这张图就理解了全部：
- 上行（发消息）：你主动调 HTTP，跟一般 REST API 没啥区别，写完就忘。
- 下行（收消息）：微信来消息时，平台 HTTP POST 推给你。这是钩子，这篇文章只聊它。
关键认知：API 主动发的消息不会触发回调。别指望调sendText之后回调里能拿到发送状态，办不到。回调只推两类东西：别人发给你的消息，和系统事件（掉线、好友申请等）。
二、回调的三个硬约束
平台给你的约束不多，就三条，但每一条都卡脖子：
| 约束 | 数值 | 你不遵守的后果 |
|---|---|---|
| 回调超时 | 6 秒 | 超时丢消息，10 分钟后平台重试 → 重复推送 |
| 重复推送 | 断线/重连/平台重启都可能触发 | 同一条消息被处理 N 次 → 重复回复、重复入库 |
| 公网可达 | 必须能从公网访问到你的回调地址 | 内网地址平台推不到 |
这三个约束决定了你回调服务的架构必须是：快速返回 + 幂等排重 + 异步处理。缺一不可。
三、一条回调数据的结构
我用的type=2（优化版），所有消息类型走统一结构：
{ "messageType": "60001", "wcId": "wxid_myself", "data": { "content": "你好，在吗？", "fromUser": "wxid_sender", "fromGroup": "", "newMsgId": 3166120021925175285, "self": false, "timestamp": 1640594470 } }四个字段是你写分发逻辑的命根子：
messageType→ 你的 switch 语句就靠它，60001是私聊文本，80001是群聊文本newMsgId→ 唯一排重键，比msgId更可靠，必须用它fromGroup→ 空了就是私聊，非空是群聊（以@chatroom结尾）self→true表示这条是你自己发的，通常直接跳过
四、你的回调 Handler 应该长这样
不废话，贴核心骨架：
app.post('/webhook', async (req, res) => { // 第一件事：立刻返回，一秒都别拖 res.json({ code: '1000', message: 'ok' }); const { messageType, data } = req.body; // 第二件事：排重 const locked = await redis.set( `msg:${data.newMsgId}`, '1', 'NX', 'EX', 3600 ); if (!locked) return; // 第三件事：跳过自己发的 if (data.self) return; // 第四件事：扔进队列 await mq.publish('wechat-message', { messageType, data }); }); // ============ 消费者（异步） ============ mq.consume('wechat-message', async ({ messageType, data }) => { switch (messageType) { case '60001': // 私聊文本 const reply = await ai.chat(data.content); await api.sendText(data.fromUser, reply); break; case '30001': // 好友申请 const { v1, v2, scene } = parseXML(data.content); await api.acceptFriend(v1, v2, scene); await api.sendText(data.fromUser, '你好，我是 AI 助理 😊'); break; case '30000': // 离线 alarm.send('微信掉线了！'); await api.reconnect(); break; } });核心思路四个字：快返异处。快速返回 + 异步处理。Handler 里不调 AI、不写库、不做任何耗时操作。
五、消息类型的规律：背不下来但能推出来
这套 API 的消息类型编码非常有规律，不需要背：
| 系列 | 范围 | 含义 |
|---|---|---|
0xxxx | 00000 | 测试推送 |
3xxxx | 30000~30003 | 系统通知（离线、好友申请、异步任务完成） |
6xxxx | 60001~60022 | 私聊消息（文本/图片/视频/语音/文件/链接/小程序/撤回……） |
65xxx | 65001~65004 | 好友关系变更（被删、被拉黑） |
8xxxx | 80001~80021 | 群聊消息（与 6xxxx 一一对应） |
85xxx | 85001~85015 | 群事件（进群/退群/改名/换群主/群公告） |
跑通一个60001（私聊文本），其他消息类型的处理逻辑几乎照搬。文件类消息唯一需要注意的是60008（上传中）和60009（上传完成）的区别——必须等60009才能下载。
六、我踩过的坑
1. 在回调里同步调 AI
大模型推理 3~10 秒是常态，超过 6 秒直接超时。平台重试 → 再超时 → 再重试，最后用户收到一串重复回复。
解法：消息入 Redis 队列 → 立即返回 200 → Worker 消费队列再调 AI。
2. 用了msgId而不是newMsgId排重
文档写得明白：newMsgId才是排重专用字段。用msgId在断线重连时不管用。
3. 忘了self字段
AI 回复之后回调又推了一条到自己，又触发 AI 再回……死循环。data.self === true直接跳过就行。
4. 多实例部署没用 Redis 排重
如果起了 3 个 Pod，同一条消息三个实例各处理一次。必须用 Redis 做分布式锁。
七、总结
用一段伪代码总结这篇文章：
收到回调 { 立刻返回 200 newMsgId 排重（Redis SETNX） 跳过 self 入队列 } 消费队列 { switch (messageType) { 30001: 自动通过好友 60001: AI 回复 80001: 群聊处理 30000: 告警 + 重连 } }Webhook 的开发哲学其实就一句：在 HTTP 层你只管收发，所有业务逻辑都交给异步。把这句刻进 DNA 里，回调就不会出大问题。
了解详情查看：Eyun官网