Webhook 本地联调

刚开始接入时，如果还没有服务器，先不用急着购买云服务器。最简单的办法是先用在线 Webhook 接收器查看 Eyun 推送内容；如果需要调试本地代码，再用临时公网通道把本地接口暴露出去。

WARNING

在线接收器和临时公网通道只适合开发联调，不建议用于正式环境。正式上线时，请改为稳定的业务服务器域名，并保证服务长期可用。

推荐方案

目标	推荐方案	为什么
只想确认 Eyun 是否推送回调	Webhook.site	打开网页复制 URL 即可，不用安装、不用注册、不用写代码
要调试本地业务代码	ngrok	文档多、命令短、Webhook 场景最常见
想用国内工具	花生壳	中文界面，适合已经有花生壳账号或更习惯国内客户端的用户

TIP

新手建议先用 Webhook.site 看一条测试推送。确认 Eyun 能正常推送后，再接入自己的本地代码。

适用场景

场景	是否适合
本地开发机验证回调格式	适合
AI 自动回复链路本地调试	适合
临时给同事演示接收消息	适合
线上业务长期接收 Webhook	不适合

方案一：只看回调内容

如果你只是想确认 Eyun 有没有推送、推送 JSON 长什么样，直接使用 Webhook.site。

1. 打开 Webhook.site。
2. 复制页面上的 Your unique URL。
3. 把这个 URL 配置到 Eyun 的 httpUrl。

示例：

curl -X POST https://api.e-yun.example/setHttpCallbackUrl \
  -H "Content-Type: application/json" \
  -H "Authorization: eyJ0eXAiOiJKV1..." \
  -d '{
    "httpUrl": "https://webhook.site/00000000-0000-0000-0000-000000000000",
    "type": 2
  }'

配置成功后，Eyun 会立即向该地址推送一条测试消息。回到 Webhook.site 页面，查看是否出现新的 POST 请求。

WARNING

Webhook.site 只适合查看回调内容，不能执行你的本地业务代码。不要把正式客户消息长期推送到第三方测试地址。

方案二：调试本地代码

如果你需要让 Eyun 调用本地接口，例如本地运行 AI 回复、入库、转发等逻辑，请按下面流程操作。

微信消息
  ↓
Eyun Webhook
  ↓
临时公网地址
  ↓
本地回调服务 http://127.0.0.1:3000/webhook

Step 1：准备本地回调服务

在本地创建 webhook-demo.js：

const http = require("http")

const server = http.createServer((req, res) => {
  if (req.method !== "POST" || req.url !== "/webhook") {
    res.writeHead(404, { "Content-Type": "application/json" })
    res.end(JSON.stringify({ error: "not found" }))
    return
  }

  let body = ""
  req.on("data", chunk => {
    body += chunk
  })

  req.on("end", () => {
    console.log("收到 Eyun Webhook：")
    try {
      console.dir(JSON.parse(body), { depth: null })
    } catch (error) {
      console.log(body)
    }

    res.writeHead(200, { "Content-Type": "application/json" })
    res.end(JSON.stringify({ code: 0, message: "ok" }))
  })
})

server.listen(3000, () => {
  console.log("Webhook demo listening on http://127.0.0.1:3000/webhook")
})

启动本地服务：

node webhook-demo.js

本地自测：

curl -X POST http://127.0.0.1:3000/webhook \
  -H "Content-Type: application/json" \
  -d '{"messageType":"00000","data":{"content":"test"}}'

如果终端能打印 JSON，说明本地回调服务可用。

Step 2：启动 ngrok

首次使用 ngrok 时，先完成三件事：

1. 打开 ngrok 官网 注册免费账号。
2. 下载并安装 ngrok 客户端。
3. 在 ngrok 控制台复制 authtoken，本地执行：

ngrok config add-authtoken <YOUR_AUTHTOKEN>

然后启动临时公网地址：

ngrok http 3000

启动后，终端会输出一个公网地址，例如：

https://abc-123.ngrok-free.app

此时 Eyun 要配置的回调地址就是：

https://abc-123.ngrok-free.app/webhook

TIP

ngrok 窗口必须保持运行。关闭窗口后，公网地址会失效；免费临时地址也可能变化。免费额度足够做开发联调，不建议用于正式环境。

如果你的网络访问 ngrok 不稳定，也可以换成花生壳。创建映射时，把本地服务地址指向：

http://127.0.0.1:3000

花生壳生成公网地址后，路径同样补 /webhook，例如：

https://abc-123.hsk.oray.com/webhook

Step 3：配置 Eyun 回调地址

把 httpUrl 替换为临时公网地址：

curl -X POST https://api.e-yun.example/setHttpCallbackUrl \
  -H "Content-Type: application/json" \
  -H "Authorization: eyJ0eXAiOiJKV1..." \
  -d '{
    "httpUrl": "https://abc-123.ngrok-free.app/webhook",
    "type": 2
  }'

成功响应：

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

配置成功后，Eyun 会立即向该地址推送一条测试消息。回到运行 node webhook-demo.js 的终端，确认是否打印了回调内容。

Step 4：触发真实消息

1. 保持本地服务和临时公网通道都在运行。
2. 用另一个微信号给当前登录的微信实例发送一条消息。
3. 查看本地终端是否打印新的 Webhook 内容。
4. 按 回调消息释义 解析 messageType 和 data。

WARNING

通过 API 主动发送的消息不会产生回调。只有对方或群成员发送到当前微信实例的消息才会回调。

方案选择

工具	适合场景	Eyun httpUrl 示例
Webhook.site	只看 Eyun 推送内容	https://webhook.site/00000000-0000-0000-0000-000000000000
ngrok	临时调试本地代码	https://abc-123.ngrok-free.app/webhook
花生壳	想用国内客户端或已有花生壳账号	以花生壳生成的公网地址为准，路径补 /webhook

常见问题

问题	处理方式
只是想看 Eyun 推了什么	优先用 Webhook.site，不需要启动本地服务
配置后收不到测试推送	确认公网地址完整可访问；本地联调时还要确认路径带 /webhook
返回“回调地址不可用”	先用 curl 向公网地址发送 POST，确认链路没有断开
本地终端没有日志	检查 Eyun 配置的 httpUrl 是否和当前公网地址一致
下次启动后又收不到回调	免费临时地址可能变化，需要重新配置 httpUrl
回调重复到达	属于可预期情况，业务系统需要按 newMsgId 做幂等

上线前替换

联调通过后，请把临时地址替换为正式业务域名：

https://api.your-company.com/eyun/webhook

正式服务建议满足：

• 使用稳定 HTTPS 域名。
• 能从公网访问，不依赖开发电脑在线。
• 6 秒内返回成功响应。
• 回调接口只做验签、入队、快速返回。
• 使用 newMsgId 或业务唯一键做幂等处理。

下一步阅读：设置回调地址。