Sign in

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

If you would like to create an endpoint to receive webhook events, you will do so from within the webhooks dashboard for your project.

  1. From the dashboard overview, navigate to the project you’d like to add webhooks to.

  2. Click on the webhooks tab from the left-hand menu.

  3. Click the “Create endpoint…” button.

  4. Enter the URL of the endpoint you would like to use. Configure with your own endpoint or generate a Svix playground link by clicking on "use Svix play".

  5. Select the events you would like to subscribe to.

  6. Click “Create 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.

Edit endpoint events

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

  1. Select the endpoint you would like to edit from the list of webhooks in the dashboard.

  2. Select “Edit endpoint…” from the top right dropdown.

  3. 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.

  1. Install the package

    Terminal
    npm install @liveblocks/node

  2. 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_...");

  3. 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.

  4. 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

  1. 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}`;

  2. 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");

  3. 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.

  4. 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

  1. 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.

  2. 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()

  3. 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

  4. 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

  5. Full example

    Here’s the full code, as detailed so far.

  6. 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 svix-cli

The svix-cli provides a listen command that creates a publicly accessible URL for testing webhooks without requiring any account setup or network configuration changes.

If your project is running on localhost:3000, you can run the following command to generate a temporary URL:

$svix listen http://localhost:3000/api/liveblocks-webhook

This will output a unique URL that forwards all POST requests to your local endpoint:

Webhook Relay is now listening at:https://play.svix.com/in/c_tSdQhb4Q5PTF5m2juiWu8qFREqE/
All requests on this endpoint will be forwarded to your local URL:http://localhost:3000/api/liveblocks-webhook
View logs and debug information at:https://play.svix.com/view/c_tSdQhb4Q5PTF5m2juiWu8qFREqE/

The generated URL can be placed directly into the Liveblocks webhooks dashboard for testing. This approach is particularly useful in enterprise environments where tools like localtunnel or ngrok may be blocked by security policies.

Using localtunnel or ngrok

Alternatively, 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

In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from the following IP addresses.

Global and US

44.228.126.21750.112.21.21752.24.126.16454.148.139.2082600:1f24:64:8000::/56

EU

52.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!

View webhook events API reference