设置回调地址

首次接入：Console Webhook

在控制台收发测试选择当前应用，保存自己的公网接收 URL；如果接收记录关闭，先阅读说明并点击「同意开启接收记录」（会保存消息正文），再测试推送。Console 管理的 Webhook 与下方兼容接口使用不同的配置入口。

• 先确认测试结果 ok=true 且 httpStatus 为 2xx，接收服务也已可靠保存测试事件。仅有管理请求成功不代表推送成功。
• 再从另一个微信账号在手机上发送文本，确认收到 X-Eyun-Event: message.received 且 messageType 为 "60001" 的消息；普通私聊文本读取 body.data.content。
• 测试事件的 type 为 webhook.test，测试说明在 body.data.message。它不代表真实微信消息已接收。

请求头	个人微信 Console 的含义
X-Eyun-Event	事件类型
X-Eyun-Event-Id	稳定事件 ID，用于去重
X-Eyun-Delivery-Attempt	本事件的推送尝试次数
X-Eyun-Signature	启用来源校验且配置密钥时，值直接等于所配置的密钥；接收端使用常量时间比较
X-Eyun-Timestamp	启用来源校验且配置密钥时携带的推送时间

个人微信当前规则不计算 HMAC。 接收端不要套用企微的 sha256= 算法，也不要把该密钥当作调用 API 的 Auth。使用 HTTPS 并避免将来源校验密钥写入日志。

Console 消息含事件级 id、type、appId、instanceId 等字段。优化版的 wcId、messageType 在顶层，消息详情保留在 data 中。以下为普通私聊文本的字段节选，示例标识已替换：

{
  "id": "evt_example",
  "type": "message.received",
  "appId": "app_example",
  "instanceId": "instance_example",
  "wcId": "wxid_receiver",
  "messageType": "60001",
  "data": {
    "fromUser": "wxid_sender",
    "toUser": "wxid_receiver",
    "newMsgId": 10001,
    "content": "首次接收测试",
    "self": false
  }
}

先校验来源、解析并可靠保存，再返回 HTTP 2xx；事件级按 X-Eyun-Event-Id 去重，消息级按账号与 data.newMsgId 去重。设置完成后继续主入门的接收确认。

兼容接口：设置回调地址

配置 Webhook URL。配置成功后，微信收到的消息和事件会以 HTTP POST 推送到该地址。

接口地址： POST /setHttpCallbackUrl

前置条件

• 回调地址必须公网可访问，HTTP/HTTPS 均可。
• 回调服务能接收 JSON 请求体。
• 回调接口检查请求格式、可靠保存事件并快速返回；耗时业务处理放异步任务，见 Webhook 可靠性。

下方兼容接口没有定义签名头或签名算法。如需额外的来源校验，请联系技术支持确认当前租户的校验方式，不要自行套用企业微信的签名规则。

TIP

没有服务器时，先用 Webhook 本地联调 查看回调内容；调试本地代码时，再把临时公网地址填入 httpUrl。

WARNING

• 消息推送超时时间为 6 秒，请快速响应。
• 若回调接口不可用，系统将在 10 分钟后重试推送。
• 配置成功后会立即收到一条“验证回调地址是否可用”的测试推送。
• 通过 API 主动发送的消息不会产生回调，只有接收到的消息和事件会回调。

请求参数

参数名	必选	类型	说明
httpUrl	是	string	回调接口 URL
type	是	int	回调格式：2 表示 优化版回调，推荐使用

响应参数

参数名	类型	说明
code	string	1000 成功，1001 失败
message	string	反馈信息

请求示例

{
  "httpUrl": "https://callback.e-yun.example/api/webhook",
  "type": 2
}

成功响应

{
  "code": "1000",
  "message": "成功",
  "data": null
}

验证与排查

场景	处理方式
配置后收到测试推送	回调地址可用，可以继续接收微信消息
收不到测试推送	检查公网访问、防火墙和服务日志；使用 HTTPS 时再检查证书
偶发重复推送	正常现象，业务系统必须按 newMsgId 等字段做幂等
回调处理慢	先入队再返回，不要在回调接口里做耗时任务

TIP

未配置回调地址时，消息默认推送至 控制台 → 在线测试 → 消息接收 模块。

下一步

配置成功后，阅读 回调事件索引，按 messageType 处理不同类型的消息和事件。