
# **Using Webhooks**

Livepeer.com 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.

### How to configure endpoints

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:

```bash
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.com/api/webhook
```

This request should return:

```json
{
  "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.

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

### Types of Events

<Table
  data={[
    {
      name: "stream.started",
      description:
        "The parent stream object's isActive value is marked as true and the .m3u8 HLS URL works",
    },
    {
      name: "stream.idle",
      description:
        "The parent stream object's isActive value should be marked as false and the .m3u8 HLS URL no longer works",
    },
    {
      name: "recording.ready",
      description: "This fires when a recording is ready to be downloaded",
    },
    {
      name: "recording.started",
      description: "This fires when recording has started on an active stream",
    },
    {
      name: "recording.waiting",
      description:
        "This 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.",
    },
    {
      name: "multistream.connected",
      description:
        "This fires when we've successfully connected to the multistream target",
    },
    {
      name: "multistream.error",
      description:
        "This fires when we've encountered an error either while attempting to connect to the third party streaming service or while broadcasting.",
    },
    {
      name: "multistream.disconnected",
      description:
        "This fires when we are no longer sending video to the multistream target.",
    },
  ]}
/>

### Retries

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


Use webhooks to listen for video lifecycle events

name	description
stream.started	The parent stream object's isActive value is marked as true and the .m3u8 HLS URL works
stream.idle	The parent stream object's isActive value should be marked as false and the .m3u8 HLS URL no longer works
recording.ready	This fires when a recording is ready to be downloaded
recording.started	This fires when recording has started on an active stream
recording.waiting	This 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.connected	This fires when we've successfully connected to the multistream target
multistream.error	This fires when we've encountered an error either while attempting to connect to the third party streaming service or while broadcasting.
multistream.disconnected	This fires when we are no longer sending video to the multistream target.