# 调试指南⭐

Webhook 调试指南

Webhook 用于接收平台推送的实时事件（登录状态、好友变化、群消息等）。事件发生时，系统向配置的回调地址发送 HTTP POST 请求，数据格式为 JSON。

Webhook 本地调试 ngrok 穿透 HTTP 200

接入流程

  1. 在控制台配置 Webhook 回调地址
  2. 启动设备并保持在线
  3. 触发相关事件（扫码登录、加好友、发送消息等）
  4. 服务端接收回调并解析 JSON 数据

回调请求说明

请求方式

```js POST Content-Type: application/json ```

回调示例

```json { "data": [{ "cmd": 15500, "msgServerId": 1017723, "msgType": 2131, "msgUniqueIdentifier": "9FcHZl98QZK_AlX", "senderId": 10030, "seq": 9409929, "timestamp": 1682676419 }], "error": 0, "msg": "成功" } ```

调试方法

本地调试

本地服务可使用 ngrok 等内网穿透工具暴露为公网地址，再填入 Webhook URL。

校验要点

常见调试问题

问题
可能原因
解决方案
收不到回调
URL 不可公网访问
检查防火墙/安全组，确保端口开放
收不到回调
地址未正确设置
重新调用 设置回调地址 接口
数据异常
解析逻辑错误
检查 JSON 结构，确认 cmd 字段
回调超时
处理过慢
先返回 200，再异步处理业务
鉴权失败
密钥不匹配
检查 authSecret 配置

建议回调处理函数先快速返回 HTTP 200，再进行耗时业务处理，避免因超时导致推送失败。