Guides / Webhooks

Webhooks

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 Authentication 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: Participant
}

Participant Left

interface WebhookEvent {
event: 'participant_left'
room: Room
participant: Participant
}

Track Published

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

interface WebhookEvent {
event: 'track_published'
room: Room
participant: Participant
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: Participant
track: TrackInfo
}

Egress Started

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

Egress Ended

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