企业微信 Webhook 如何配置
更新于 2026-06-09·约 5 分钟
Webhook 配置看似只是「填个地址」，但要稳定收事件，地址可达性、验签、响应时延与重试处理缺一不可。下面给出一份可照做的清单。
配置前的准备
- 一个可公网访问、走 HTTPS 的回调地址（本地联调可用内网穿透）。
- 处理服务能在数百毫秒内返回响应，重活一律异步。
- 记录原始请求的能力，便于排查与重放。
配置与验签
- 1在控制台填写回调地址，保存后会有一次验证请求。
- 2在服务端按文档算法完成验签，正确回应验证串。
- 3订阅你需要的事件类型，避免全量订阅带来噪声。
示意：本地用内网穿透联调bash
# 将本地 3000 暴露到公网，拿到 https 地址填进控制台
ngrok http 3000
# => https://xxxx.ngrok.app -> http://localhost:3000响应与重试
提示Webhook 方通常按非 2xx 或超时进行重试。请先返回 2xx 再异步处理，并对重复投递做幂等，否则会出现重复执行。
常见问题
- Webhook 和消息回调是一回事吗？
- 可以理解为同一类机制：平台以 HTTP 主动把事件推到你配置的地址。配置层关注地址与订阅，处理层关注验签、响应与幂等。
- 本地开发收不到回调怎么办？
- 本地地址不可公网访问，需用内网穿透（如 ngrok）拿到 https 地址再填入控制台。
- 为什么会重复收到同一事件？
- 响应超时或返回非 2xx 会触发重试。先快速 2xx、再异步处理，并用事件 ID 做幂等即可避免重复执行。
准备好动手了？
精确字段、鉴权与端点以线上文档为准；可在控制台创建密钥后联调。