设置回调地址

回调地址是你的接收程序地址，Eyun 会把微信收到的消息和事件推送到这里。推荐在控制台配置；已有程序用接口配置的，见下方兼容接口。

首次接入：在控制台配置

三步配好

在控制台应用凭证页右栏「收进来」配置：填入你自己的公网接收地址，点击「保存并测试」。保存后会自动发一条测试推送，几秒内显示结果；显示「收到了」且 HTTP 状态是 2xx，接收程序也已保存这条测试事件，才算地址可用。只看到保存成功还不够。
需要校验推送来源时，在「收进来」点「生成密钥」，把密钥配到接收程序。密钥只显示一次；之后每条推送的 X-Eyun-Signature 都带上它。这一步可以跳过。
用另一个微信账号，在手机上给当前登录账号发一条文字消息。接收程序收到 X-Eyun-Event: message.received、messageType 为 "60001" 的推送，在 body.data.content 读到这条文字，就接通了。

还没有公网地址时，先点「开始实时查看」看 Eyun 推给你的原文（不保存消息），或用 eyun 命令行把推送转发到本机。测试推送的 type 是 webhook.test，说明文字在 body.data.message，它不代表真实微信消息已经收到。

接收程序要做的事

先校验来源、解析并可靠保存，再返回 HTTP 2xx。
事件按 X-Eyun-Event-Id 去重，消息按账号与 data.newMsgId 去重。newMsgId 最长 19 位，JavaScript 里按字符串处理，见大整数。
换密钥时点「换密钥…」，换完立即生效、旧密钥马上作废，接收端更新之前会拒收推送。
个人微信当前规则不计算 HMAC。 接收端不要套用企微的 sha256= 算法，也不要把密钥当作调用凭证。使用 HTTPS，不要把密钥写进日志。

推送格式

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

控制台推送的消息含事件级 id、type、appId、instanceId 等字段。优化版格式的 wcId、messageType 在顶层，消息详情在 data 里。以下是普通私聊文本的字段节选，示例标识已替换：

json

{
  "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
  }
}

配好后回到快速开始完成接收确认。

兼容接口：设置回调地址

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

接口地址： POST /setHttpCallbackUrl

用本接口设置的地址，也会出现在控制台

调用本接口后，地址会同步到控制台「应用凭证」里名为「旧版token」的应用，右栏「收进来」会注明「这个地址是你的程序调 /setHttpCallbackUrl 设的」。在控制台改了之后，程序再调用一次本接口，会覆盖控制台里的修改。本接口只作用于「旧版token」应用，不影响你在控制台新建的其他应用。

前置条件

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

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

TIP

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

WARNING

消息推送超时时间为 6 秒，请快速响应。
若回调接口不可用，系统将在 10 分钟后重试推送。
调用时会先往这个地址发一条测试推送；发不通直接返回失败「连接回调url失败」，地址不会保存。
服务重启或微信重新登录后，推送可能延迟 1 秒到 10 分钟，属正常现象。
通过 API 主动发送的消息不会产生回调，只有接收到的消息和事件会回调。

请求参数

参数名	必选	类型	说明
httpUrl	是	string	回调接口 URL
type	是	int	回调格式：传 `2`，用优化版回调。不传或传其他值是旧格式

响应参数

参数名	类型	说明
code	string	`1000` 成功；其他值都是失败，通常是 `1001`
message	string	反馈信息

请求示例

http

POST {BASE_URL}/setHttpCallbackUrl
Authorization: Bearer <你的调用凭证>
Content-Type: application/json

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

bash

curl -X POST '{BASE_URL}/setHttpCallbackUrl' \
  -H 'Authorization: Bearer <你的调用凭证>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "httpUrl": "https://callback.e-yun.example/api/webhook",
  "type": 2
}'

python

import requests

url = "{BASE_URL}/setHttpCallbackUrl"
headers = {"Authorization": "Bearer <你的调用凭证>", "Content-Type": "application/json"}
body = """{
  "httpUrl": "https://callback.e-yun.example/api/webhook",
  "type": 2
}"""

resp = requests.post(url, headers=headers, data=body.encode("utf-8"))
print(resp.text)

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String url = "{BASE_URL}/setHttpCallbackUrl";
String body = "{\n" +
    "  \"httpUrl\": \"https://callback.e-yun.example/api/webhook\",\n" +
    "  \"type\": 2\n" +
    "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(url))
    .header("Authorization", "Bearer <你的调用凭证>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

php

<?php

$url = '{BASE_URL}/setHttpCallbackUrl';
$body = <<<'JSON'
{
  "httpUrl": "https://callback.e-yun.example/api/webhook",
  "type": 2
}
JSON;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <你的调用凭证>',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

成功响应

json

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

验证与排查

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

TIP

未配置回调地址时，Eyun 不会把消息推给你的程序。想先看推送内容，在控制台应用凭证页右栏「收进来」点「开始实时查看」（不保存消息）。

下一步

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

设置回调地址 ​

首次接入：在控制台配置 ​

三步配好 ​

接收程序要做的事 ​

推送格式 ​

兼容接口：设置回调地址 ​

前置条件 ​

请求参数 ​

响应参数 ​

请求示例 ​

成功响应 ​

验证与排查 ​

下一步 ​