Eyun 开发者文档

Appearance

本地联调 ​

回调地址必须公网可访问；开发阶段没有公网地址时，按下面两条路径之一先把回调跑通。

路径适合做法
路径一 · 看报文还没写接收代码，想先看清推送长什么样用在线请求接收器拿一个临时公网地址，直接看请求头和请求体
路径二 · 调本地代码接收代码已写好，要调验签、去重与处理逻辑本地起服务，用内网穿透工具（如 ngrok、cpolar）把本地端口暴露成公网地址

临时地址只用于开发，不要接收正式客户消息

上线前把回调地址换成你自己的正式地址，重新设置并测试投递。

路径一 · 在线请求接收器 ​

  1. 打开一个在线请求接收器，拿到它生成的临时 URL。
  2. 调设置或更新回调地址，url 填这个临时 URL。首次创建时返回 data.secret，先保存好；更新已有配置不返回也不改密钥。
  3. 调测试投递，在接收器里看到一条请求头 X-Eyun-Event: webhook.test 的推送，并确认测试响应 data.ok=true 且 data.httpStatus 为 2xx。

路径二 · 本地服务 + 内网穿透 ​

  1. 按回调说明 · 收到推送后怎么处理里的参考写法在本地起服务。验签必须用原始请求体，参考写法里用的是 express.raw。
  2. 用内网穿透工具（如 ngrok、cpolar）把本地服务的端口暴露出去，拿到一个公网地址。
  3. 调设置或更新回调地址，url 填「公网地址 + 接收路径」（如参考写法里的 /hook）。首次创建时，把返回的 data.secret 配给本地服务；从临时地址切换过来属于更新，继续用之前保存的密钥，响应不会再次返回它。参考写法从环境变量 EYUN_WEBHOOK_SECRET 读取；密钥丢失的处理见回调说明。
  4. 调测试投递，本地服务收到 webhook.test，验签并可靠入队后返回 HTTP 2xx（建议返回 {}）。确认测试响应里的 data.ok=true 且 data.httpStatus 为 2xx；data.httpStatus 是你的服务返回的状态，不能只看测试接口的 HTTP 200。
  5. 用另一个企微账号在客户端给这个账号手动发一句话，本地服务收到请求头 X-Eyun-Event: message.received 的推送。

为什么要用客户端手动发

经接口发出的消息不推正文，只推一条已读回执（contentType 2001）。

验收 ​

检查怎么做通过标准
测试投递调测试投递响应里的 data.ok=true 且 data.httpStatus 为 2xx
验签带一个错误的 X-Eyun-Signature 请求你的地址不进入处理，参考写法返回 401
去重把收到的同一个 X-Eyun-Delivery 的推送原样再发一次不重复处理
收消息在客户端手动发一句话收到 message.received，contentType 为 0 或 2

下一步 ​