LiveKit.WebhookReceiver (LiveKit v0.1.0)

Copy Markdown View Source

Validates LiveKit webhook callbacks and decodes them into LiveKit.Proto.WebhookEvent.

LiveKit POSTs JSON with Content-Type: application/webhook+json and an Authorization header holding a JWT whose sha256 claim is the Base64 SHA-256 of the raw request body. Pass that raw body (binary or iodata), not a pre-decoded map:

iex> {:ok, receiver} = LiveKit.WebhookReceiver.new(api_key: "k", api_secret: "s")
iex> body = ~s({"event":"room_started","id":"EV_1"})
iex> {:ok, event} = LiveKit.WebhookReceiver.receive(receiver, body, nil, skip_auth: true)
iex> event.event
"room_started"

When authentication is enabled (the default), the JWT is verified with LiveKit.TokenVerifier and the body digest must match claims["sha256"].

Summary

Types

t()

Functions

new(opts_or_client)

Builds a receiver from keyword credentials or a LiveKit.Client.

new!(opts)

Same as new/1 but raises LiveKit.Error on failure.

receive(receiver, body, auth_header, opts \\ [])

Verifies and decodes a webhook request.

Types

t()

@type t() :: %LiveKit.WebhookReceiver{verifier: LiveKit.TokenVerifier.t()}

Functions

new(opts_or_client)

@spec new(keyword() | LiveKit.Client.t()) :: {:ok, t()} | {:error, LiveKit.Error.t()}

Builds a receiver from keyword credentials or a LiveKit.Client.

Examples

iex> {:ok, receiver} = LiveKit.WebhookReceiver.new(api_key: "k", api_secret: "s")
iex> receiver.verifier.api_key
"k"

new!(opts)

@spec new!(keyword() | LiveKit.Client.t()) :: t()

Same as new/1 but raises LiveKit.Error on failure.

receive(receiver, body, auth_header, opts \\ [])

@spec receive(t(), iodata(), String.t() | nil, keyword()) ::
  {:ok, LiveKit.Proto.WebhookEvent.t()} | {:error, LiveKit.Error.t()}

Verifies and decodes a webhook request.

Arguments

  • receiver - a LiveKit.WebhookReceiver
  • body - raw POST body as a binary or iodata
  • auth_header - value of the Authorization header (JWT, optionally prefixed with Bearer). Ignored when :skip_auth is true.
  • opts - see below

Options

Examples

iex> receiver = LiveKit.WebhookReceiver.new!(api_key: "k", api_secret: "s")
iex> {:error, error} = LiveKit.WebhookReceiver.receive(receiver, "{}", nil)
iex> error.type
:authentication