Webhooks

Configure LiveKit to notify your server when room events take place.

Overview

LiveKit can be configured to notify your server when room events take place. This can be helpful for your backend to know when a room has finished, or when a participant leaves.

With Cloud, webhooks can be configured in the Settings section of your project's dashboard.

When self-hosting, webhooks can be enabled by setting the webhook section in your config.

webhook:
# The API key to use in order to sign the message
# This must match one of the keys LiveKit is configured with
api_key: 'api-key-to-sign-with'
urls:
- 'https://yourhost'

Receiving webhooks

Webhook requests are HTTP POST requests sent to URLs that you specify in your config or Cloud dashboard. A WebhookEvent is encoded as JSON and sent in the body of the request.

The Content-Type header of the request is set to application/webhook+json. Please ensure your webserver is configured to receive payloads with this content type.

In order to ensure webhook requests are coming from LiveKit, these requests have an Authorization header containing a signed JWT token. The token includes a sha256 hash of the payload.

LiveKit's server SDKs provide webhook receiver libraries which should help with validation and decoding of the payload.

import { WebhookReceiver } from 'livekit-server-sdk';
const receiver = new WebhookReceiver('apikey', 'apisecret');
// In order to use the validator, WebhookReceiver must have access to the raw
// POSTed string (instead of a parsed JSON object). If you are using express
// middleware, ensure that `express.raw` is used for the webhook endpoint
// app.use(express.raw({type: 'application/webhook+json'}));
app.post('/webhook-endpoint', async (req, res) => {
// Event is a WebhookEvent object
const event = await receiver.receive(req.body, req.get('Authorization'));
});

Delivery and retries

Webhooks are HTTP requests initiated by LiveKit and sent to your backend. Due to the protocol's push-based nature, there are no guarantees around delivery.

LiveKit aims to mitigate transient failures by retrying a webhook request multiple times. Each message will undergo several delivery attempts before being abandoned. If multiple events are queued for delivery, LiveKit will properly sequence them; only delivering newer events after older ones have been delivered or abandoned.

Events

In addition to the fields below, all webhook events will include the following fields:

  • id - a UUID identifying the event
  • createdAt - UNIX timestamp in seconds

Room Started

interface WebhookEvent {
event: 'room_started';
room: Room;
}

Room Finished

interface WebhookEvent {
event: 'room_finished';
room: Room;
}

Participant Joined

interface WebhookEvent {
event: 'participant_joined';
room: Room;
participant: ParticipantInfo;
}

Participant Left

interface WebhookEvent {
event: 'participant_left';
room: Room;
participant: ParticipantInfo;
}

Track Published

In the Room and Participant objects, only sid, identity, and name are sent.

interface WebhookEvent {
event: 'track_published';
room: Room;
participant: ParticipantInfo;
track: TrackInfo;
}

Track Unpublished

In the Room and Participant objects, only sid, identity, and name are sent.

interface WebhookEvent {
event: 'track_unpublished';
room: Room;
participant: ParticipantInfo;
track: TrackInfo;
}

Egress Started

interface WebhookEvent {
event: 'egress_started';
egressInfo: EgressInfo;
}

Egress Updated

interface WebhookEvent {
event: 'egress_updated';
egressInfo: EgressInfo;
}

Egress Ended

interface WebhookEvent {
event: 'egress_ended';
egressInfo: EgressInfo;
}

Ingress Started

interface WebhookEvent {
event: 'ingress_started';
ingressInfo: IngressInfo;
}

Ingress Ended

interface WebhookEvent {
event: 'ingress_ended';
ingressInfo: IngressInfo;
}