Webhooks

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.

Webhooks can be configured in Project Settings section of the Cloud Dashboard.

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'

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.

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

In order to ensure the requests are coming from LiveKit, webhook 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'))
})

import (
  "github.com/livekit/protocol/auth"
  "github.com/livekit/protocol/livekit"
  "github.com/livekit/protocol/webhook"
)

func ServeHTTP(w http.ResponseWriter, r *http.Request) {
  authProvider := auth.NewSimpleKeyProvider(
    apiKey, apiSecret,
  )
  // event is a livekit.WebhookEvent{} object
  event, err := webhook.ReceiveWebhookEvent(r, authProvider)
  if err != nil {
    // could not validate, handle error
    return
  }
  // consume WebhookEvent
}

import io.livekit.server.*;

WebhookReceiver webhookReceiver = new WebhookReceiver("apiKey", "secret");

// postBody is the raw POSTed string.
// authHeader is the value of the "Authorization" header in the request.
LivekitWebhook.WebhookEvent event = webhookReceiver.receive(postBody, authHeader);

// consume WebhookEvent

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

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

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

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

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

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

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

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

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

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

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