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:

1. Navigate to the developer section of the dashboard, and then go to the Webhooks section.
2. 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.
3. Check the Real-time box.
4. Choose whether to receive a single request or a batch of messages.
5. If choosing batch messages, configure the frequency of sendouts.
6. 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.