企业微信消息回调怎么做

先分清：「消息回调」是四段链路，不是一个接口

搜这个问题的人想要的往往是一句「地址填在哪」。但回调上线之后真正出问题的，几乎从来不是填地址那一步。把它拆开，这件事至少由四段构成，每一段的失败表现完全不同，排查入口也完全不同。

• 配置与握手：告诉平台往哪推、推哪些事件。这一段的产物是一个地址加一组订阅项，改动一次就意味着一段有真实事件正在流动的切换窗口，所以要一次定对。
• 验签：回调地址通常是整个集成里唯一对公网开放写入的入口，它的身份校验只能由验签负责，不能让业务鉴权代劳，也不该两套叠着用。
• 接收与响应：你多久回一个 2xx。这一段决定了对方要不要重试，也就直接决定了你会不会收到重复事件。
• 消费与回写：解析、路由、落库，命中规则后调用发送接口把结果写回会话。只有这一段会产生对外可见的副作用。

前置条件与准备

下面这几项在动手写代码之前就该备齐。缺任意一项，后面都会以「上线后才发现」的形式还回来。

• 一个可公网访问的 HTTPS 地址，且证书链完整。证书过期或中间证书缺失在浏览器里可能只是一个警告，在服务端的 HTTP 客户端那边多半直接是连接失败，而且失败得很安静 —— 没有人收到通知，事件就是不来了。
• 一个能独立部署、独立重启的薄接收端。不要把它直接挂在业务进程上，业务每重启一次就丢一批事件，这两件事的生命周期不该绑在一起。
• 一条队列，加一张能存原始报文的表。原始报文是后面所有重放、对账、复现的唯一依据，丢了就什么都做不了。
• 把回调路径显式排除在业务鉴权中间件之外。回调请求既没有 Cookie 也没有你签发的 Token，全局登录校验会把它整整齐齐全挡在门外，日志里只剩一片鉴权失败。
• 测试、预发、生产各配各的地址。wecomapi 的账号接入支持实例隔离，用同一个地址靠查询参数区分环境，等于把一次配置手误直接兑现成给真实客户发消息。
• 本地联调用内网穿透拿一个临时 https 地址即可，不要把开发机地址填进生产配置。

分步骤接入

1. 1在控制台创建密钥、填写回调地址并保存。保存时平台会发一次验证请求，你的服务按文档约定回应即可。判据是控制台显示配置已生效，而不是你本地日志里出现过一条请求 —— 握手只证明这个地址是你的，不代表常态推送已经通了。
2. 2只订阅当前真的会处理的事件类型。wecomapi 的事件回调覆盖消息、成员、客户与群四类事件，全开的代价不是流量而是噪声：日志里九成是你不看的东西，之后每次排查都要先做一遍筛选。判据是接收端日志里出现的事件类型，能和你路由表里登记的类型一一对上。
3. 3把验签写成接收端的第一道逻辑，用原始字节校验，不要用框架解析并重新序列化过的 body。签名字段与算法以线上接口文档为准。判据：手工改掉报文里的一个字节再重放，应当返回 401，并且队列里不新增任何记录。
4. 4先 ACK 再干活。从收到请求到返回 2xx 之间只做三件事：验签、落原始报文、入队，控制在数百毫秒内。判据是接收端的响应时延曲线是平的，不随下游数据库或模型接口的抖动起伏。
5. 5消费端按事件类型分流，每类事件一个独立消费者，互不阻塞。幂等键放在消费入口，不要埋在业务代码深处。事件的唯一标识取哪个字段以线上接口文档为准。判据：同一条事件重放三次，业务侧只产生一次副作用。
6. 6命中规则后回写。调用发送接口把结果写回会话，并把响应头里的 x-request-id 与这条事件的原始报文关联存下来。判据是随便抽一条已完成的业务动作，都能反查到触发它的那条报文和这次调用的标识。

app.post("/wecom/callback", async (req, res) => {
  // 1. 用原始字节验签；框架解析后重新序列化过的 body 会导致签名对不上
  if (!verifySignature(req.rawBody, req.headers)) return res.sendStatus(401);

  // 2. 先把原始报文落下来 —— 重放与对账都只认它
  const stored = await rawStore.put(req.rawBody);

  // 3. 再 ACK。这一步之前不要有任何业务查询
  res.sendStatus(200);

  // 4. 入队，解析、路由、回写全部在消费端做
  await queue.enqueue({ topic: "wecom.event", rawId: stored.id });
});

# 消费端命中规则后，把结果写回会话
curl -i -X POST "https://manager.wecomapi.com/message/sendText" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "guid":    "7db8...",
    "toId":    "78813...",
    "content": "已收到，正在为你查询。"
  }'

# 响应体只说明这次调用本身的结果：
# { "code": 0, "msg": "success" }
#
# 加 -i 是为了拿到这两个响应头，它们不在响应体里：
# x-request-id: req_7d4ec1a9      排障时提供它即可定位到这一次调用
# x-ratelimit-remaining: 98       剩余额度，用来提前降速而不是等被限流
#
# 其余端点、字段与错误码取值以线上接口文档为准。

架构与数据流：谁调谁、状态存哪、谁负责重试

一条事件从平台走到业务系统，中间只经过三个角色，它们可以独立扩容、独立故障，把边界画清楚，出问题时才有地方下刀。

• 平台 → 接收端：整条链路上唯一一次由外部发起的调用。接收端不做业务判断、不查业务库，只负责验签、落盘、入队、回 2xx。
• 接收端 → 队列 → 消费者：状态从这里开始归你。原始报文存在你自己的存储里，队列只负责调度，两者不要互相替代 —— 队列里放的应当是引用，不是整份报文。
• 消费者 → 业务系统 → 发送接口：唯一会产生对外副作用的一段。回写走 REST 调用，鉴权与幂等语义和其他接口一致。

重试责任必须划分清楚，否则容易出现两头都在重试、或者两头都以为对方会重试。第一跳由平台负责重试，你能做的只有尽快回 2xx 和把幂等做好；第一跳之后的所有重试都归你 —— 消费失败进重试队列，反复失败进死信。回写失败则要先分类再决定：网络超时这类结果未知的，按幂等语义重试是安全的；参数或权限这类确定性失败，重试多少次结果都一样，应当直接进死信等人处理。

错误处理与排障

回调链路的故障，多数不是「坏了」，而是「慢了」或者「悄悄少了一部分」。按上面三个角色把链路切开，每一段定一个能一刀切开责任的观测点，大部分问题能先定位到段、再深挖。

1. 1网络层：接收端的访问日志里有没有这条请求。有，说明第一跳是通的，问题在你这边，不用再去问对方；一条都没有，才往地址可达性、证书、网关或 WAF 拦截的方向查。
2. 2验签层：验签失败通常不是算法写错了，而是报文在到达验签函数之前被谁动过 —— 代理改了编码、框架重新序列化过 body、日志中间件先把流读走了。先把原始字节长度打出来对一下，比逐行读算法快得多。
3. 3响应层：看接收端的响应时延分布。一旦有一部分请求超过对方的超时阈值，你会同时观察到两个现象：重复事件变多、事件整体延迟变大。它们是同一个原因，不要当成两个问题分头查。
4. 4队列层：看堆积深度和消费速率。堆积持续上涨说明消费者不够或某个下游变慢了，此时事件并没有丢，只是在排队，先别急着重放 —— 在积压期间重放只会把队列压得更死。
5. 5业务层：看死信。死信里堆着的才是真正需要人介入的东西，其余各层的异常大多会自愈。

回写侧的报错建议按「该做什么」分类，而不是按码值去背。确定性失败：参数或权限问题，重试无意义，直接进死信。状态失败：对象当前状态不允许这个动作，需要业务层决策而不是重试。容量失败：触发限流，退避后重试，并对照响应头 x-ratelimit-remaining 提前降速而不是等被拒。结果未知：超时或连接中断，按幂等语义重试是安全的。具体的错误码取值以线上接口文档为准。

这四段每一段都能单独展开，站内的深入文章按段分工：《企微回调接口怎么配置和验签》把配置、验签、响应、重试拆成四段讲，包括握手与常态验签为什么不是一件事；《企业微信 Webhook 重复投递与幂等设计》讲幂等键该拼什么、去重窗口按什么定、存 Redis 还是数据库唯一索引；《企业微信消息处理为什么必须走队列》讲同步处理的三种崩法，以及重放与死信这两件最容易做错的事；《企业微信事件回调延迟与丢失怎么排查》则把上面这套分段展开成一套可照着走的五段定位法。本页是总纲，需要落到某一段的细节时再进去看。

怎么判断你做对了

「能收到消息了」不是验收标准。下面几条是可观察的判据，全部成立，这条链路才算可以承接生产流量。

• 把报文改掉一个字节再投递，返回 401，且队列里不新增任何记录。
• 同一条事件连续投递三次，业务侧只产生一次副作用，另外两次在幂等层被丢弃并留下计数 —— 计数为零反而说明幂等逻辑根本没被走到。
• 人为让下游数据库慢 3 秒，接收端的响应时延不受影响，压力体现在队列深度上而不是响应时延上。
• 把消费者停掉十分钟再启动，积压的事件全部补齐，业务结果与不停机时一致。
• 随机抽一条已完成的业务动作，能反查到触发它的原始报文，以及回写调用返回的 x-request-id。
• 死信队列里一有东西就有人被告知。死信是空的不代表没问题，也可能只是根本没接告警。

这几条跑通之后再逐步放量。生产上通常还会留一条主动查询的补偿路径做对账：回调为主、查询为辅，两边对不上时以主动查询的结果为准。wecomapi 的事件回调本身提供签名校验、投递重试与死信观测，但对账口径、重放策略和告警阈值这几件事只能由你按业务定，没有通用默认值。