HTTP Webhooks

Search…
🔗
HTTP Webhooks
Before diving into the webhooks documentation, consider reading Pusher's documentation regarding webhooks to understand the basics of webhooks when using the Pusher protocol.
Each app definition contains a webhooks array which will contain data structures formatted like the following:
1
{
2
 "url": "string",
3
 "event_types": ["string", ...]
4
}
Copied!
url - The URL where the data will be sent.
event_types - An array of strings with the events that will trigger the webhook.
The value for event_types can be one of the following:
client_event
channel_occupied
channel_vacated
member_added
member_removed
The generic look of a webhook's payload is the same as Pusher's:
1
{
2
 "time_ms": 1327078148132,
3
 "events": [
4
 { "name": "event_name", "some": "data" },
5
 { "name": "event_name", "some": "data" },
6
 .
7
 .
8
 .
9
 ]
10
}
Copied!
Each event from events looks like this:
1
{
2
 "name": "client_event",
3
 "channel": "name of the channel the event was published on",
4
 "event": "name of the event",
5
 "data": "data associated with the event",
6
 // "socket_id": "socket_id of the sending socket", - not applicable yet
7
 // "user_id": "user_id associated with the sending socket" - not applicable yet, only for presence channels
8
}
Copied!
Filtering Webhooks
Enabling webhooks will send notifications for the selected event_types, but for all channels. In some situations, you may want to receive webhooks for specific channels, to simply reduce the network usage.
1
{
2
 "url": "string",
3
 "event_types": ["channel_occupied"],
4
 "filter": {
5
 "channel_name_starts_with": "beta-",
6
 "channel_name_ends_with": "-app"
7
 }
8
}
Copied!
1
// Won't trigger the webhook
2
client.subscribe('chat-room');
3
client.subscribe('beta-chat-room');
4
client.subscribe('chat-room-app');
5
​
6
// Will trigger the webhook
7
client.subscribe('beta-chat-room-app');
Copied!
All passed filters are combined with AND logic. To filter them by another logical gate like OR, consider filtering most of the events by passing the filters object and consider modifying your webhook server's code to filter them further.
Webhook Headers
​Thanks to @stayallive's PR, you can pass additional headers that will be sent within the webhook request:
1
{
2
 "url": "string",
3
 "event_types": ["channel_occupied"],
4
 "headers": {
5
 "X-Custom-Header": "Custom Header",
6
 "X-Version": "Custom Header"
7
 }
8
}
Copied!
Webhook Batching
​Dan Pegg submitted a Pull Request that allows you to send webhooks in batches rather than on one-by-one basis. This can become useful when you don't want to send a request for each event through the webhooks, but rather give some time for more events to build up and fire all of them at once, in a single request.
To enable batching, use the WEBHOOKS_BATCHING environment variable:
1
SOKETI_WEBHOOKS_BATCHING=1 soketi start
Copied!
The build up of events is done in 50 ms by default. On receiving an event, it waits 50 ms before sending the webhook. In those 50 ms, more events can come and build up. Once the 50 ms mark was reached, the events are being sent in one request.
If you have a lot of webhooks going on, consider increasing this value according to your needs. In the submitted Pull Request, a use case was the AWS Lambda functions webhook handling, which incurs costs based on how much the function is running and based on how many requests are done. For high-traffic apps that use those webhooks, increasing the batch duration is important, so that requests are sent at a lower rate, but with more events.
1
# Setting the duration to 1000ms = 1s
2
SOKETI_WEBHOOKS_BATCHING=1 SOKETI_WEBHOOKS_BATCHING_DURATION=1000 soketi start
Copied!
Make sure that your graceful shutdown period is higher than the batch durations. If you set the batching higher than the graceful shutdown allowance, you may never receive the events that were still built up before being flushed out of the memory with the server shutdown.
Advanced Usage - Previous
Prometheus Metrics
AWS Lambda trigger
Last modified 1mo ago
Copy link
Contents
Filtering Webhooks
Webhook Headers
Webhook Batching