Webhooks

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.

Configuring webhooks

To set up webhooks for your project, you’ll need to create an endpoint, subscribe to events, and secure your endpoint.

Creating an endpoint
Testing an endpoint
Edit endpoint events
Security verification
Replaying events
Testing locally

Creating an 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.

From the dashboard overview, navigate to the project you’d like to add webhooks to.
Click on the webhooks tab from the left-hand menu.
Click the “Add endpoint…” button.
Enter your endpoint URL, or click “use a test endpoint” to generate a URL at https://webhooks.liveblocks.io/test/<token>.
Select the events you would like to subscribe to.
Click “Add endpoint”.

Your endpoint must return a 2xx (status code 200-299) to indicate that the event was successfully received. If your endpoint returns anything else, the event will be retried, see replaying events for more details.

If all events fail to be delivered to your endpoint for 5 consecutive days, your endpoint will automatically be disabled. You can always re-enable it from the dashboard.

Testing an endpoint

To inspect webhook requests without running your own server, create an endpoint using “use a test endpoint” in the add endpoint form.

Select the endpoint, open its top right menu, and choose “Test endpoint…”.
Select an event type and click “Send example”.
Open the event in the delivery history. Under “Webhook attempts”, open the attempt’s menu and choose “Show response body”.

The response body contains a JSON receipt with the request time, method, URL, selected request headers, and up to 4 KiB of the request body. The truncated field indicates whether any part of the receipt was shortened.

Test endpoints don’t forward requests to your local server. To test your own webhook handler locally, follow testing locally.

Edit endpoint events

You can easily edit the events you want to subscribe to after creating an endpoint.

Select the endpoint you would like to edit from the list of webhooks in the dashboard.
Select “Edit endpoint…” from the top right dropdown.
Update event selections and click “Save changes”.

Replaying events

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 top right dropdown and selecting “Recover 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:

Immediately
5 seconds
5 minutes
30 minutes
2 hours
5 hours
10 hours
10 hours (in addition to the previous)

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

Security verification

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. We recommend using the @liveblocks/node package to verify and return fully typed events.

Install the package
Terminal
npm install @liveblocks/node

Set up the webhook handler

Set up your webhook handler, inserting your secret key from the webhooks dashboard you set up earlier into WebhookHandler.

import { WebhookHandler } from "@liveblocks/node";
// Insert your webhook secret keyconst webhookHandler = new WebhookHandler("whsec_...");

Verify an event request
We can verify a genuine webhook request with WebhookHandler.verifyRequest
const event = webhookHandler.verifyRequest({ headers: req.headers, rawBody: req.body,});
rawBody takes a string
Note that some frameworks parse request bodies into objects, so you may need to use rawBody: JSON.stringify(req.body) instead.
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.

Full example

Here’s an example from start to finish.

import { WebhookHandler } from "@liveblocks/node";
// Will fail if not properly initialized with a secretconst webhookHandler = new WebhookHandler("whsec_...");
export default function webhookRequestHandler(req, res) {  try {    const event = webhookHandler.verifyRequest({      headers: req.headers,      rawBody: req.body,    });
    // Use the event, for example...    if (event.type === "storageUpdated") {      // { roomId: "my-room-name", projectId: "8sfhs5s...", ... }      console.log(event.data);    }  } catch (error) {    console.error(error);    return res.status(400).end();  }
  res.status(200).end();}

Manually verify in Node.js

It’s also possible to manually verify your webhooks in Node.js, though it’s unlikely this’ll be necessary.

How to manually verify webhook events in Node.js

Construct the signed content

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:

const crypto = require("crypto");
// webhookId comes from the `webhook-id` header// webhookTimestamp comes from the `webhook-timestamp` header// body is the request bodysignedContent = `${webhookId}.${webhookTimestamp}.${body}`;

Generate the signature
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 webhook secret key (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:
// Your endpoint’s secret keyconst secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"; // Need to base64 decode the secretconst secretBytes = new Buffer(secret.split("_")[1], "base64");// This is the signature you will compare against the signature headerconst signature = crypto.createHmac("sha256", secretBytes).update(signedContent).digest("base64");
Validate the signature
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:
v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=
Make sure to remove the version prefix and delimiter (e.g., v1) before verifying the signature.
Verify the timestamp
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.
Comparing signatures
We recommend implementing a constant-time string comparison method when comparing signatures to prevent timing attacks.

Manually verify in Elixir

It’s also possible to manually verify your webhooks in Elixir using Plug/Phoenix, especially if you want to validate Liveblocks webhooks before parsing the request body.

How to manually verify webhook events in Elixir

Construct the signed content
The signed content is composed by concatenating the webhook ID, timestamp, and request body, separated by dots (.). In Elixir, it looks like this:
signed_content = "#{webhook_id}.#{webhook_timestamp}.#{body}"
- webhook_id comes from the "webhook-id" header.
- webhook_timestamp comes from the "webhook-timestamp" header.
- body is the raw request body.

Generate the signature

Liveblocks signs webhooks using HMAC with SHA-256. You need to use the base64-decoded portion of your secret (after the whsec_ prefix) as the key.

Example in Elixir:

secret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
# Extract and decode the base64 part of the secretsecret_bytes =  secret  |> String.split("_")  |> Enum.at(1)  |> Base.decode64!()
# Compute the signaturesignature =  :crypto.mac(:hmac, :sha256, secret_bytes, signed_content)  |> Base.encode64()

Validate the signature

The signature you just generated should match one of the signatures from the webhook-signature header. That header contains space-separated values like:

v1,abc123= v1,def456= v2,ghi789=

You should extract just the Base64-encoded signature (the part after the comma):

signature_header = get_req_header(conn, "webhook-signature") |> List.first()
webhook_signatures =  signature_header  |> String.split(" ")  |> Enum.map(fn entry ->    entry |> String.split(",") |> Enum.at(1)  end)

Then check if your generated signature is in the list:

if signature in webhook_signatures do  # Valid signatureend

Verify the timestamp
Liveblocks includes a webhook-timestamp header to help prevent replay attacks. You should check that the timestamp is within a reasonable window (e.g., 5 minutes):
tolerance = 5 * 60now = :os.system_time(:second) case Integer.parse(webhook_timestamp) do {ts, _} when abs(now - ts) <= tolerance -> true _ -> falseend
Full example
Here’s the full code, as detailed so far.
Add to your endpoint module
Finally, to use the validator to your endpoint module, place it before Plug.parsers.
plug(App.Plugs.RequestValidator)plug(Plug.Parsers, ...)

Testing locally

Running webhooks locally can be difficult, but there are several tools that allow you to temporarily host your localhost server online.

Using localtunnel or ngrok

You can use tools such as localtunnel or ngrok which also allow you to temporarily host your localhost server online.

If your project is running on localhost:3000, you can run the following command to generate a temporary URL that’s available while your localhost server is running:

Terminal

npx localtunnel --port 3000

If you visit the page localtunnel links you to, and correctly input your IP address, the URL it generates can be placed into the Liveblocks webhooks dashboard for quick testing.

For a full step-by-step guide on testing with localtunnel and ngrok, read the guide on how to test webhooks on localhost.

Source IP Addresses

Webhooks are not sent from a fixed set of IP addresses, so we don't recommend restricting your endpoint by source IP. If your endpoint is behind a firewall or NAT, allow incoming traffic from any IP address, and use signature verification to confirm that requests were sent by Liveblocks.

Previously published IP addresses (no longer valid)

We used to send webhooks from the IP addresses below. They're only listed here for reference, and webhooks are no longer guaranteed to come from these sources. If your firewall or NAT configuration only allows traffic from these addresses, update it to allow traffic from any IP address instead, otherwise future webhook deliveries to your endpoint may fail.

Global and US:

❌ Remove these from your allowlist if you added them in the past44.228.126.21750.112.21.21752.24.126.16454.148.139.2082600:1f24:64:8000::/56

EU:

❌ Remove these from your allowlist if you added them in the past52.215.16.23954.216.8.7263.33.109.1232a05:d028:17:8000::/56

Webhook events

Webhook events are sent when users or systems change Liveblocks data. You can subscribe an endpoint to all events or select specific events in the webhooks dashboard.

For example, storageUpdated is sent after a Storage document changes, and commentCreated is sent after a comment is created:

const storageUpdatedEvent = {  type: "storageUpdated",  data: {    projectId: "my-project-id",    roomId: "my-room-id",    updatedAt: "2021-10-06T01:45:56.558Z",  },};
const commentCreatedEvent = {  type: "commentCreated",  data: {    projectId: "my-project-id",    roomId: "my-room-id",    threadId: "my-thread-id",    commentId: "my-comment-id",    createdAt: "2021-10-06T01:45:56.558Z",    createdBy: "my-user-id",  },};

Use cases

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:

Storage synchronization between room(s) and an internal database
Monitoring user activity in a room
Notifying the client if maximum concurrency has been reached

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!

Webhooks

Install the package

Set up the webhook handler

Verify an event request

Full example

Construct the signed content

Generate the signature

Validate the signature

Verify the timestamp

Construct the signed content

Generate the signature

Validate the signature

Verify the timestamp

Full example

Add to your endpoint module