收到消息不做排重？回调里同步调 AI？6 秒超时不返回？——我在接入微信 API 的 Webhook 时踩过的坑，都写在这了。

前言：一个真实的需求

去年接了一个项目，需求很简单：把客户的个人微信变成 AI 客服，自动回复消息。

听起来不难是吧？API 发消息、收消息，两个接口的事。结果 Webhook 上线第一天，甲方的微信里同一个问题被 AI 回了五遍——因为断线重连触发了重复推送。

所以这篇文章不谈业务，就聊一件事：怎么做才算接对了 Webhook。

一、先理解：回调在整个系统里的位置

┌──────────┐ HTTP POST ┌──────────┐ WebSocket ┌────────┐ │ 你的服务 │ ←──────────── │ 开放平台 │ ←─────────── │ 微信 │ │ │ │ │ │ │ │ 你的服务 │ ─────────────→│ 开放平台 │ ─────────────→│ 微信 │ └──────────┘ HTTP POST └──────────┘ HTTP API └────────┘

看懂这张图就理解了全部：

• 上行（发消息）：你主动调 HTTP，跟一般 REST API 没啥区别，写完就忘。
• 下行（收消息）：微信来消息时，平台 HTTP POST 推给你。这是钩子，这篇文章只聊它。

关键认知：API 主动发的消息不会触发回调。别指望调sendText之后回调里能拿到发送状态，办不到。回调只推两类东西：别人发给你的消息，和系统事件（掉线、好友申请等）。

二、回调的三个硬约束

平台给你的约束不多，就三条，但每一条都卡脖子：

这三个约束决定了你回调服务的架构必须是：快速返回 + 幂等排重 + 异步处理。缺一不可。

三、一条回调数据的结构

我用的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 的消息类型编码非常有规律，不需要背：

跑通一个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官网