Webhook
You can configure a webhook to allow you to receive real-time data about events that are published by the Real-time Channels. Our server will send a POST request to the URL you specify in the webhook when the event occurs.
How to receive real-time data via webhook
Follow these steps to add a new webhook, allowing you to receive event data in real-time:
- Navigate to the developer section of the dashboard, and then go to the Webhooks section.
- Specify the URL in which you will receive every message, provide a description for the webhook, and input a token if necessary for your end.
- Check the Real-time box.
- Choose whether to receive a single request or a batch of messages.
- If choosing batch messages, configure the frequency of sendouts.
- Save your settings.
Single request
When selecting the single request mode, the server will send a POST request to the URL you specified every time an event occurs. Be aware that this mode may generate a high volume of requests, depending on the activity in the room.
It's designed for a maximum of 30 events that can be dispatched as soon as they are available (limited to 15 for free users). In case of failure, the event will be re-queued and re-sent every 2 seconds, increasing exponentially up to 5 minutes. If an error with a status code 5XX or timeout occurs, the delay between attempts will double, from 2 to 4 seconds.
Here is an example of the payload you will receive:
{
"apiKey": "YOUR_KEY",
"roomId": "ROOM_ID",
"channel": "CHANNEL_NAME",
"event": "EVENT_NAME",
"date": "2024-05-17T20:56:59.006Z",
"data": {
// YOUR DATA
},
"presenceId": "55x7kd",
"socketId": "oxulmrXc_A-_3olrAAAr",
}
Batch request
When selecting the batch request mode, the server will send a POST request to the URL you specified according to the frequency you specified. The server will batch the messages into a list and then send it in a single request.
When using batch mode, the system will send up to 1,000 events at a time. If more than 1,000 events are sent, they will be queued and sent in the next batch request.
Here is an example of the payload you will receive:
[
{
"apiKey": "YOUR_KEY",
"roomId": "ROOM_ID",
"channel": "CHANNEL_NAME",
"event": "EVENT_NAME",
"date": "2024-05-17T20:56:59.006Z",
"data": {
// YOUR DATA
},
"presenceId": "55x7kd",
"socketId": "oxulmrXc_A-_3olrAAAr",
},
{
"apiKey": "YOUR_KEY",
"roomId": "ROOM_ID",
"channel": "CHANNEL_NAME",
"event": "EVENT_NAME",
"date": "2024-05-17T20:56:59.009Z",
"data": {
// YOUR DATA
},
"presenceId": "55x7kd",
"socketId": "oxulmrXc_A-_3olrAAAr",
}
]
Realtime data structure
The Real-time data sent by the webhook have a basic structure that includes the following fields:
Field name | Type | Description |
---|---|---|
apiKey | string | The API key used to start the room. |
roomId | string | The room ID where the event occurred. |
channel | string | The channel name where the event occurred. |
event | string | The event name. |
date | string | The date and time when the event occurred. |
data | object | The data payload sent with the event. |
presenceId | string | The ID of the participant. |
socketId | string | The connection ID of the connection used to publish the message. This value can be nullable, meaning that the event wasn't dispatched by a participant. |