设置回调地址

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

接口地址： POST /setHttpCallbackUrl

前置条件

• 回调地址必须是公网可访问的 HTTP/HTTPS URL。
• 回调服务需要能接收 JSON 请求体。
• 建议回调接口只做验签、入队、快速返回，业务处理放到异步任务中。

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 处理不同类型的消息和事件。