Skip to main content
IntroductionBuild AgentsAgent FrontendsTest & EvaluateTelephonyRoboticsWebRTC TransportManage & DeployReferences
XYouTubeSlack

Webhooks

Subscribe to the room, participant, track, egress, and ingress events for a project.

Overview

A webhook delivers the events from a project to a URL you control. A project can subscribe to its room, participant, track, egress, and ingress events. For what each event means, see Webhooks.

When you leave signingKey empty, LiveKit signs deliveries with the oldest key of the project that isn't an agent key, and stores that key as the webhook's signing key. Adding keys later doesn't change it. If the project has no such key, the request returns 400.

Listing webhooks and event types needs the Read role on the project. Creating, updating, deleting, and sending a test event need the Write role.

To call these endpoints from the CLI, use the lk project webhook commands, for example lk project webhook list --user-auth.

The webhook object

A webhook destination of a project.

idstring

The webhook ID.

namestring

A label for the destination.

urlstring

The URL that receives the events.

signingKeystring

The API key of this project whose secret signs each delivery. It is a key ID, not a secret. Empty signs with the oldest key in the project.

filterParamsFilterParams

The events to send, named by includeEvents or excludeEvents. Read the names from List webhook events.

To learn more, see FilterParams.

The webhook object

{
  "id": string,
  "name": string,
  "url": string,
  "signingKey": string,
  "filterParams": FilterParams
}

List webhooks

GET
/v0/projects/{projectId}/webhooks

Lists the webhook destinations for the project, in the order that they were added. The list is always one page.

Returns the full list of Webhook objects.

Path parameters

projectId
Required
string

The project ID (p_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/webhooks" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "id": "g6XsddOuxpVhFTCdEAqBCL",
      "name": "order-events",
      "url": "https://example.com/hooks/livekit",
      "signingKey": "APIeU7rRlbo7Xp1",
      "filterParams": {
        "includeEvents": [
          "room_started",
          "room_finished"
        ],
        "excludeEvents": []
      }
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  }
}

Create webhook

POST
/v0/projects/{projectId}/webhooks

Returns the Webhook object.

Path parameters

projectId
Required
string

The project ID (p_...).

Request body

namestring

A label for the destination.

urlstring

The HTTP or HTTPS URL that receives the deliveries as POST requests.

signingKeystring

The API key of this project whose secret signs the deliveries. Optional. When empty, the API uses the oldest API key of the project and saves it on the webhook.

filterParamsFilterParams

The names of the events to deliver, from ListWebhookEvents. When unset, the webhook gets every event.

To learn more, see FilterParams.

Request

curl -X POST "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/webhooks" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-events",
    "url": "https://example.com/hooks/livekit",
    "filterParams": {
      "includeEvents": [
        "room_started",
        "room_finished"
      ]
    }
  }'

Response

{
  "webhook": {
    "id": "g6XsddOuxpVhFTCdEAqBCL",
    "name": "order-events",
    "url": "https://example.com/hooks/livekit",
    "signingKey": "APIeU7rRlbo7Xp1",
    "filterParams": {
      "includeEvents": [
        "room_started",
        "room_finished"
      ],
      "excludeEvents": []
    }
  }
}

Update webhook

PATCH
/v0/projects/{projectId}/webhooks/{webhookId}

Returns the Webhook object.

Path parameters

projectId
Required
string

The project ID (p_...).

webhookId
Required
string

The webhook ID.

Request body

The changes to a webhook. An unset field keeps its value.

namestring

The project name.

urlstring

The URL that receives the events.

signingKeystring

The API key of this project whose secret signs the deliveries. When unset or empty, the signing key does not change.

filterParamsFilterParams

The names of the events to deliver. A set filter replaces the whole filter. An empty filter delivers every event.

To learn more, see FilterParams.

Request

curl -X PATCH "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/livekit/v2"
  }'

Response

{
  "webhook": {
    "id": "g6XsddOuxpVhFTCdEAqBCL",
    "name": "order-events",
    "url": "https://example.com/hooks/livekit/v2",
    "signingKey": "APIeU7rRlbo7Xp1",
    "filterParams": {
      "includeEvents": [
        "room_started",
        "room_finished"
      ],
      "excludeEvents": []
    }
  }
}

Delete webhook

DELETE
/v0/projects/{projectId}/webhooks/{webhookId}

Path parameters

projectId
Required
string

The project ID (p_...).

webhookId
Required
string

The webhook ID.

Request

curl -X DELETE "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{}

Send test webhook

POST
/v0/projects/{projectId}/webhooks/{webhookId}:test

Path parameters

projectId
Required
string

The project ID (p_...).

webhookId
Required
string

The webhook ID.

Request body

eventstring

The event to send: one of the names from ListWebhookEvents. The API sends it with sample data and ignores the webhook filter.

Response fields

statusCodeint32

The HTTP status of the response from the receiver. 0 when no response arrived.

errorstring

The reason that no response arrived, such as a timeout or a refused connection. Empty when statusCode is set.

Request

curl -X POST "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/webhooks/${WEBHOOK_ID}:test" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "room_started"
  }'

Response

{
  "statusCode": 200,
  "error": ""
}

List webhook events

GET
/v0/projects/{projectId}/webhook-events

Lists the event names that the webhooks of a project can receive. The list is always one page.

Returns the full list of string values.

Path parameters

projectId
Required
string

The project ID (p_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/webhook-events" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    "room_started",
    "room_finished",
    "participant_joined",
    "participant_left",
    "participant_connection_aborted",
    "track_published",
    "track_unpublished",
    "egress_started",
    "egress_updated",
    "egress_ended",
    "ingress_started",
    "ingress_ended"
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  }
}