In this guide, we will explain how to use webhooks within your product so that you can react to Liveblocks events as they happen. Now that our platform is observable, you can use webhooks to reduce development time and the need for polling.
To set up webhooks for your project, you’ll need to create an endpoint, subscribe to events, and secure your endpoint.
If you would like to create an endpoint to receive webhook events, you will do so from within the webhooks dashboard for your project.
By default, each endpoint provided in the webhooks dashboard listens to all events. However, you can easily configure it to only listen to a subset of events by updating the "Subscribed events" section after creating the endpoint
If your service is unreachable, message retries are automatically re-attempted. If your service incurs considerable downtime (over 8 hours), you can replay individual messages from the Endpoints portion of the dashboard by clicking the kebab menu on an individual message, or you can opt to bulk replay events by clicking the main menu and selecting “Replay Failed Messages.”
Each message is attempted based on a schedule that follows the failure of the preceding attempt. If an endpoint is removed or disabled, delivery attempts will also be disabled. The schedule for retries is as follows:
For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.
Verifying webhooks prevents security vulnerabilities by safeguarding against man-in-the-middle, CSRF, and replay attacks. Because of this, it is essential to prioritize verification in your integration.
There are two ways to verify your webhooks, either manually or by using the
@liveblocks/node package. We highly recommend using the
package to verify and return fully typed events.
The method will return a
WebhookEvent object that is fully typed. You can then
use the event to perform actions based on the event type.
If the request is not valid, an error will be thrown.
The content to sign is composed by concatenating the request’s id, timestamp,
and payload, separated by the full-stop character (
.). In code, it will look
Liveblocks uses an HMAC with SHA-256 to sign its webhooks.
So to calculate the expected signature, you should HMAC the
above using the base64 portion of your signing secret (this is the part after
whsec_ prefix) as the key. For example, given the secret
whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw you will want to use
For example, this is how you can calculate the signature in Node.js:
The generated signature should match one of the signatures sent in the
webhook-signature header comprises a list of space-delimited signatures
and their corresponding version identifiers. The signature list is most commonly
of length one. Though there could be any number of signatures. For example:
Make sure to remove the version prefix and delimiter (e.g.,
verifying the signature.
As mentioned above, Liveblocks also sends the timestamp of the attempt in the
webhook-timestamp header. You should compare this timestamp against your
system timestamp and make sure it’s within your tolerance to prevent timestamp
An event occurs when a change is made to Liveblocks data. Each endpoint you provide in the webhooks dashboard listens to all events by default but can be easily configured to only listen to a subset by updating the Message Filtering section.
The Event Catalog in the webhooks dashboard provides a list of events available for subscription, along with their schema.
Events available for use include:
More events will come later, such as:
When a user connects to a room, an event is triggered, indicating that the user
has entered. The
numActiveUsers field shows the number of users in the room
after the user has joined. This event is not throttled.
A user leaves a room when they disconnect from a room, which is when this event
is triggered. The
numActiveUsers field represents the number of users in the
room after the user has left. This event, like
UserEntered, is not throttled.
Storage is updated when a user writes to storage. This event is throttled at five minutes and, as such, may not be triggered for every write.
For example, if a user writes to storage at 1:00 pm, the
event will be triggered shortly after. If the user writes to storage again at
1:01 pm, the
StorageUpdatedEvent event will be triggered 5 minutes after the
first event was sent, around 1:05 pm.
An event is triggered when a room is created. This event is not throttled. There are two ways for rooms to be created:
An event is triggered when a room is deleted. This event is not throttled.
With webhooks, you can subscribe to the events you are interested in, and be alerted of the change when it happens. Powerful ways to leverage webhooks with Liveblocks include:
Webhooks are an excellent way to reduce development time and the need for polling. By following the steps outlined in this guide, you’ll be able to configure, subscribe to, secure, and replay webhook events with Liveblocks.
If you have any questions or need help using webhooks, please let us know by email or by joining our Discord community! We’re here to help!