Skip to main content

​
Webhook Callbacks

​
Overview

Some data from WuKongIM will be sent to third-party application services through webhooks, such as user online status, messages that need to be pushed, all messages, etc. All webhooks are POST requests, and the event name is passed through query parameters. For example, if the third-party server provides a webhook address of http://example.com/webhook, then the online status webhook would be: 
http://example.com/webhook?event=user.onlinestatus
The request body data would be similar to: 
["uid1-0-1", "uid2-1-0"]

​
Webhook Workflow

Webhook workflow diagram

​
Event Types

​
1. User Online Status Notification

Each user’s online and offline status will be notified to the third-party server through this webhook. Event Name: user.onlinestatus Request Method: POST Request URL: {webhook_url}?event=user.onlinestatus

​
Request Body

The request body is a string array, each element formatted as: 
UserUID-DeviceFlag-OnlineStatus-ConnectionID-DeviceOnlineCount-UserTotalOnlineCount
Example Data: 
["uid1-1-0-1001-2-4", "uid2-0-0-1001-1-2"]

​
Data Field Description

PositionField NameTypeDescription
1User UIDstringUser unique identifier
2Device Flaginteger0=APP, 1=Web
3Online Statusinteger0=Offline, 1=Online
4Connection IDintegerConnection ID established by current device on server
5Device Online CountintegerOnline count for same user and same device type
6User Total Online CountintegerTotal online count for all user devices
# Simulate webhook request sent by WuKongIM
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. Offline Message Notification

Offline message notification mainly notifies the third-party server of messages that need to be pushed offline. After receiving this webhook, the third-party server needs to call mobile vendor push interfaces to push the message content to users in the ToUIDs list. Event Name: msg.offline Request Method: POST Request URL: {webhook_url}?event=msg.offline

​
Request Body

The request body is a MessageResp message object:
​
header
object
Message header information
​
setting
integer
Message setting identifier
​
message_id
integer
Server message ID (globally unique)
​
message_idstr
string
String type server message ID (globally unique)
​
client_msg_no
string
Client message unique number
​
message_seq
integer
Message sequence number (channel unique, ordered increment)
​
from_uid
string
Sender UID
​
channel_id
string
Channel ID
​
channel_type
integer
Channel type
​
timestamp
integer
Server message timestamp (10 digits, to seconds)
​
payload
string
Base64 encoded message content
​
to_uids
array
Recipient user list
​
to_uids[]
string
Recipient user UID
// Receive offline message webhook
app.post('/webhook', (req, res) => {
  const event = req.query.event;
  
  if (event === 'msg.offline') {
    const message = req.body;
    
    // Decode message content
    const payload = JSON.parse(atob(message.payload));
    
    // Send push notification to users in to_uids
    message.to_uids.forEach(uid => {
      sendPushNotification(uid, {
        title: `Message from ${message.from_uid}`,
        body: payload.content,
        messageId: message.message_idstr
      });
    });
  }
  
  res.status(200).send('OK');
});

​
3. All Messages Notification

WuKongIM server will push all messages to the third-party server. To reduce pressure on the third-party server, messages are not pushed one by one but with delay processing. By default, batch push occurs every 500 milliseconds (webhook.msgNotifyEventPushInterval), which can be configured as needed. Event Name: msg.notify Request Method: POST Request URL: {webhook_url}?event=msg.notify

​
Request Body

The request body is an array of MessageResp message objects, each containing the following fields:
​
[].header
object
Message header information
​
[].setting
integer
Message setting identifier
​
[].message_id
integer
Server message ID (globally unique)
​
[].message_idstr
string
String type server message ID (globally unique)
​
[].client_msg_no
string
Client message unique number
​
[].message_seq
integer
Message sequence number (channel unique, ordered increment)
​
[].from_uid
string
Sender UID
​
[].channel_id
string
Channel ID
​
[].channel_type
integer
Channel type
​
[].timestamp
integer
Server message timestamp (10 digits, to seconds)
​
[].payload
string
Base64 encoded message content
// Receive all messages webhook
app.post('/webhook', (req, res) => {
  const event = req.query.event;
  
  if (event === 'msg.notify') {
    const messages = req.body; // Message array
    
    messages.forEach(message => {
      // Decode message content
      const payload = JSON.parse(atob(message.payload));
      
      // Save message to database or search engine
      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');
});

​
Configure Webhook

Set the webhook URL in the WuKongIM configuration file: 
webhook:
  url: "http://your-server.com/webhook"
  timeout: 5s
  msgNotifyEventPushInterval: 500ms

​
Best Practices

  1. Response Speed: Webhook processing should be as fast as possible to avoid blocking WuKongIM service
  2. Idempotency: Ensure webhook processing is idempotent and can be safely retried
  3. Error Handling: Return appropriate HTTP status codes, 2xx indicates success
  4. Async Processing: For complex business logic, recommend asynchronous processing
  5. Monitoring & Alerting: Monitor webhook success rate and response time
  6. Security Verification: Verify request source to prevent malicious requests

​
Troubleshooting

​
Common Issues

  1. Webhook Not Received: Check URL configuration and network connectivity
  2. Processing Timeout: Optimize processing logic to reduce response time
  3. Duplicate Processing: Implement idempotent processing mechanism
  4. Message Loss: Ensure correct HTTP status codes are returned