Livepeer Studio

Using 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, we’ll make a POST request to a URL that you specify.

Webhook endpoints are specific for each event. Once the event is registered, all streams for this account will be triggering the specific event. Here is an example of registering for the stream.started and stream.idle events:

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"
  }' \

This request should return:

  "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"

Now all streams will trigger the stream.started and stream.idle events for this account.

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

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.

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