Skip to main content

Listen for webhooks

The following includes information and instructions on how to work with Webhooks to communicate with your application:

  • Use webhooks to listen for video lifecycle events
  • Check webhook signatures to ensure incoming webhook requests are coming from Livepeer

About Webhooks​

Livepeer Studio uses webhooks to communicate with your application asynchronously when events for your stream occur. For example, you may want to know when a stream has become active or idle, so that you can surface this information to viewers. When these events happen, you can make a POST request to a URL that you specify.

Types of Events​

NameDescription
stream.startedThe parent stream object's isActive value is marked as true and the .m3u8 HLS URL works
stream.idleThe parent stream object's isActive value should be marked as false and the .m3u8 HLS URL no longer works
recording.readyThis fires when a recording is ready to be downloaded
recording.startedThis fires when recording has started on an active stream
recording.waitingThis fires after a stream with recording on has concluded and is not yet ready to be downloaded. Typically it takes 5 minutes for recordings to be ready for download.
multistream.connectedThis fires when we've successfully connected to the multistream target
multistream.errorThis fires when we've encountered an error either while attempting to connect to the third party streaming service or while broadcasting.
multistream.disconnectedThis fires when we are no longer sending video to the multistream target.
asset.createdThis fires when a On Demand asset is created.
asset.updatedThis fires when a On Demand asset is updated.
asset.readyThis fires when a On Demand asset is ready.
asset.failedThis fires when a On Demand asset fails during the upload or during processing.
asset.deletedThis fires when a On Demand asset is deleted.
task.spawnedThis fires when a task is spawned. (For example, an On Demand upload)
task.updatedThis fires when a task is updated.
task.completedThis fires when a task completes its execution successfully.
task.failedThis fires when a task has failed.

Configuring Webhook Endpoints​

Webhook endpoints are specific for each event. Once the event is registered, all streams for this account will be triggering the specific event.

For Example: Registering for stream.started and stream.idle events:

Request​

This cURL request registers a stream.started and stream.idle event so that all streams will trigger the stream.started and stream.idle events for this account.

curl \
    -X POST \
    -H "authorization: Bearer {api_key}" \
    -H "content-type: application/json" \
    --data-raw '{
      "events": ["stream.started", "stream.idle"],
      "url": "{webhook_url}",
      "name": "test webhooks"
  }' \
  https://livepeer.studio/api/webhook

Response​

Returns a JSON object with the webhook object just created. This includes its id, name, the events it will be notified about and the url that will be called.

{
  "createdAt": 1624939859628,
  "events": ["stream.started", "stream.idle"],
  "id": "e7b8a281-8952-4791-b837-183cb95bbf32",
  "kind": "webhook",
  "name": "test webhooks",
  "url": "{webhook_endpoint}",
  "userId": "ffcd3b74-9908-4d23-be05-58e1480e752a"
}

Retries​

Currently, if a webhook fails, Livepeer will attempt to deliver the webhook for ~15 minutes with an exponential back-off.

Other Webhooks Endpoints​

GET /api/webhook: Get a list of webhooks

GET /api/webhook/:webhookID: Get a single webhook Object details

PUT /api/webhook/:webhookID: Edit a webhook, using the same parameters as POST /webhook

DEL /api/webhook/:webhookID: Delete a webhook

Webhook Signatures​

You can verify webhook requests that Livepeer Studio sends to your endpoints, using the request header signature included by Livepeer Studio. This signature will help you verify the incoming request comes from Livepeer Studio and not a third party.

  • Livepeer Studio will include a signature in each event’s Livepeer-Signature header.

  • The timestamp is prefixed by t= and the signature is prefixed by a scheme.

  • Schemes start with v, followed by an integer. Currently, the only valid signature scheme is v1. Livepeer Studio generates signatures using HMAC with SHA2-256.

Livepeer-Signature: t=36285904404,v1=88f3ff0fds9sf8a98vb0b096e81507cfd5c932fc17cf63a4a55566fd38da3a2d3d2

Validate the signature, take the following steps:​

Extract the timestamp and signatures from the header​

  1. Split the header, using the , character as the separator, to get a list of elements.

  2. Split each element, using the = character as the separator, to get a prefix and value pair.

  • The value for the prefix t corresponds to the timestamp, and
  • v1 corresponds to the signature (or signatures). You can discard all other elements.

Prepare the signed_payload string​

The signed_payload is the raw request payload.

It is important to Note: that the JSON in the request payload includes the same timestamp from the signature header to protect against replay attacks.

Determine the expected signature​

Compare the signature (or signatures) in the header to the expected signature.

  • For an equality match compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

  • To protect against timing attacks: use a constant-time string comparison to compare the expected signature to each of the received signatures.