Webhook 调试指南

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

Webhook本地调试ngrok 穿透HTTP 200

接入流程

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

回调请求说明

请求方式

回调示例

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

调试方法

本地调试

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

校验要点

回调接口须返回 HTTP 200
地址须公网可访问
按 JSON 格式正确解析数据

常见调试问题

问题

可能原因

解决方案

收不到回调

URL 不可公网访问

检查防火墙/安全组，确保端口开放

收不到回调

地址未正确设置

重新调用 设置回调地址 接口

数据异常

解析逻辑错误

检查 JSON 结构，确认 cmd 字段

回调超时

处理过慢

先返回 200，再异步处理业务

鉴权失败

密钥不匹配

检查 authSecret 配置

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

调试指南⭐

Webhook 调试指南#

接入流程#

回调请求说明#

调试方法#

本地调试#

校验要点#