跳转到主要内容

​
Webhook 回调

​
概述

WuKongIM 的一些数据将通过 webhook 的形式回调给第三方应用服务，比如用户在线状态，需要推送的消息，所有消息等等。所有 webhook 都是 POST 请求，事件名通过 query 参数传入。 例如，第三方的服务器提供的 webhook 地址为 http://example.com/webhook，那么在线状态的 webhook 为： 
http://example.com/webhook?event=user.onlinestatus
请求体的数据类似为： 
["uid1-0-1", "uid2-1-0"]

​
Webhook 工作流程

Webhook 工作流程图

​
事件类型

​
1. 用户在线状态通知

每个用户的上线和下线都会通过此 webhook 通知给第三方服务器。 事件名：user.onlinestatus 请求方式：POST 请求 URL：{webhook_url}?event=user.onlinestatus

​
请求体

请求体是一个字符串数组，每个元素格式为： 
用户UID-设备标识-在线状态-连接ID-设备标识对应的设备在线数量-用户总个设备在线数量
示例数据： 
["uid1-1-0-1001-2-4", "uid2-0-0-1001-1-2"]

​
数据字段说明

位置字段名类型说明
1用户UIDstring用户唯一标识符
2设备标识integer0=APP, 1=Web端
3在线状态integer0=离线, 1=在线
4连接IDinteger当前设备在服务器的建立连接的ID
5设备在线数量integer同一用户同一设备类型的在线数量
6用户总在线数量integer用户所有设备的在线数量
# 模拟 WuKongIM 发送的 webhook 请求
curl -X POST "http://your-server.com/webhook?event=user.onlinestatus" \
  -H "Content-Type: application/json" \
  -d '["user123-1-1-1001-1-1", "user456-0-0-1002-0-0"]'

​
2. 离线消息通知

离线消息通知主要是将需要通过离线推送的消息通知给第三方服务器，第三方服务器收到此 webhook 后需要将此消息内容调用手机厂商推送接口，将消息推给 ToUIDs 列表的用户。 事件名：msg.offline 请求方式：POST 请求 URL：{webhook_url}?event=msg.offline

​
请求体

请求体是一个 MessageResp 消息对象：
​
header
object
消息头部信息
​
setting
integer
消息设置标识
​
message_id
integer
服务端的消息ID（全局唯一）
​
message_idstr
string
字符串类型服务端的消息ID（全局唯一）
​
client_msg_no
string
客户端消息唯一编号
​
message_seq
integer
消息序列号（频道唯一，有序递增）
​
from_uid
string
发送者UID
​
channel_id
string
频道ID
​
channel_type
integer
频道类型
​
timestamp
integer
服务器消息时间戳（10位，到秒）
​
payload
string
Base64编码的消息内容
​
to_uids
array
接收用户列表
​
to_uids[]
string
接收用户UID
// 接收离线消息 webhook
app.post('/webhook', (req, res) => {
  const event = req.query.event;
  
  if (event === 'msg.offline') {
    const message = req.body;
    
    // 解码消息内容
    const payload = JSON.parse(atob(message.payload));
    
    // 发送推送通知给 to_uids 中的用户
    message.to_uids.forEach(uid => {
      sendPushNotification(uid, {
        title: `来自 ${message.from_uid} 的消息`,
        body: payload.content,
        messageId: message.message_idstr
      });
    });
  }
  
  res.status(200).send('OK');
});

​
3. 所有消息通知

WuKongIM 服务端会将所有消息推送给第三方服务器。为了降低第三方服务器的压力，并不是一条一条推送，做了延迟处理，默认是 500 毫秒（webhook.msgNotifyEventPushInterval）批量推送一次，这个可自己视情况配置。 事件名：msg.notify 请求方式：POST 请求 URL：{webhook_url}?event=msg.notify

​
请求体

请求体是一个 MessageResp 消息对象数组，每个消息对象包含以下字段：
​
[].header
object
消息头部信息
​
[].setting
integer
消息设置标识
​
[].message_id
integer
服务端的消息ID（全局唯一）
​
[].message_idstr
string
字符串类型服务端的消息ID（全局唯一）
​
[].client_msg_no
string
客户端消息唯一编号
​
[].message_seq
integer
消息序列号（频道唯一，有序递增）
​
[].from_uid
string
发送者UID
​
[].channel_id
string
频道ID
​
[].channel_type
integer
频道类型
​
[].timestamp
integer
服务器消息时间戳（10位，到秒）
​
[].payload
string
Base64编码的消息内容
// 接收所有消息 webhook
app.post('/webhook', (req, res) => {
  const event = req.query.event;
  
  if (event === 'msg.notify') {
    const messages = req.body; // 消息数组
    
    messages.forEach(message => {
      // 解码消息内容
      const payload = JSON.parse(atob(message.payload));
      
      // 保存消息到数据库或搜索引擎
      saveMessageToDatabase({
        messageId: message.message_idstr,
        fromUid: message.from_uid,
        channelId: message.channel_id,
        channelType: message.channel_type,
        content: payload,
        timestamp: message.timestamp
      });
    });
  }
  
  res.status(200).send('OK');
});

​
配置 Webhook

在 WuKongIM 配置文件中设置 webhook URL： 
webhook:
  url: "http://your-server.com/webhook"
  timeout: 5s
  msgNotifyEventPushInterval: 500ms

​
最佳实践

  1. 响应速度：webhook 处理应该尽可能快，避免阻塞 WuKongIM 服务
  2. 幂等性：确保 webhook 处理是幂等的，可以安全地重试
  3. 错误处理：返回适当的 HTTP 状态码，2xx 表示成功
  4. 异步处理：对于复杂的业务逻辑，建议异步处理
  5. 监控告警：监控 webhook 的成功率和响应时间
  6. 安全验证：验证请求来源，防止恶意请求

​
故障排除

​
常见问题

  1. Webhook 未收到：检查 URL 配置和网络连通性
  2. 处理超时：优化处理逻辑，减少响应时间
  3. 重复处理：实现幂等性处理机制
  4. 消息丢失：确保返回正确的 HTTP 状态码