Server / Webhooks

Webhooks

On this page

Overview

Receiving webhooks

Events

Room Started

Room Finished

Participant Joined

Participant Left

Track Published

Track Unpublished

Egress Started

Egress Ended

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.

When self-hosting, webhooks can be enabled by setting the webhook section in 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 the config. A WebhookEvent is sent as the body of the request, encoded in JSON.

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

LiveKit server SDKs provide webhook receiver libraries that will 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
// router.use('/webhook/path', express.raw());
app.post('/webhook-endpoint', (req, res) => {
// event is a WebhookEvent object
const event = receiver.receive(req.body, req.get('Authorization'))
})

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 Ended

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