Webhooks enable developers to extend the Liveblocks platform. From your system, you can listen to events that get automatically triggered as users interact with collaborative rooms.
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 @liveblocks/node
package to verify and return fully typed events.
@liveblocks/node
With 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
something like:
Liveblocks uses an HMAC with SHA-256 to sign its webhooks.
So to calculate the expected signature, you should HMAC the signedContent
from
above using the base64 portion of your signing secret (this is the part after
the whsec_
prefix) as the key. For example, given the secret
whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
you will want to use
MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
.
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.
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., v1
) before
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
attacks.
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:
StorageUpdated
UserEntered/UserLeft
RoomCreated/RoomDeleted
More events will come later, such as:
MaxConnectionsReached
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 StorageUpdatedEvent
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.
Yjs document is updated when a user makes a change to a Yjs doc connected to a room. This event is throttled at five minutes and, as such, may not be triggered for every write.
For example, if a user updates a yjs document at 1:00 pm, the YDocUpdatedEvent
event will be triggered shortly after. If the user writes to storage again at
1:01 pm, the YDocUpdatedEvent
event will be triggered 5 minutes after the
first event was sent, around 1:05 pm.
An event is triggered when a comment is created. This event is not throttled.
An event is triggered when a comment is edited. This event is not throttled.
An event is triggered when a comment is deleted. This event is not throttled.
An event is triggered when a thread is created. This event is not throttled.
An event is triggered when a thread metadata is updated. 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!