❗️

Media Hooks

The Recording Hooks are being deprecated and replaced by Media Hooks.

At your convenience, you should transition the type of webhooks you have enabled and receive in your service. For customers who continue to use Recording Hooks we'll reach out and provide assistance before this event type is removed.

The recordings type of webhook allows you to receive state changes for platform events during recording such as when a recording is started, completed, or deleted.

See the Recordings guide for more details about recording a stream and how to retrieve downloads.

Event

The event will be one of the following values:

• started is sent when a recording has been started.
• completed is sent when a recording has been fully processed and is available for download.
• deleted is sent when the recording has been removed from storage and is no longer available.
• error is sent when there has been an error processing the recording.

Data

The data will include the following values:

• recordFileId is a unique identifier for the recording file.
• tokenId is a unique identifier for the publishing token used to create the recording.
• streamName is the stream name the recording was created for.
• recordedOn is an epoch time for when the recording started.

You may also optionally see:

• removedOn for the epoch time when the recording was deleted (only for deleted events).
• metadata which includes details such as format, sizes, duration, and tracks (only for completed events).

Examples

Recording Started

When a recording has been started.

{
  "type": "recordings",
  "event": "started",
  "timestamp": 1639296462907,
  "data": {
    "recordFileId": 7975,
    "tokenId": 142366,
    "streamName": "sample_stream",
    "recordedOn": 1639296462755
  }
}

Recording Completed

When a recording has been stopped, processed and available for download. See the Recordings guide for more details on viewing or downloading recordings.

{
  "type": "recordings",
  "event": "completed",
  "timestamp": 1639296471486,
  "data": {
    "recordFileId": 7975,
    "tokenId": 142366,
    "streamName": "sample_stream",
    "recordedOn": 1639296463000,
    "metadata": {
      "format": "MPEG-4",
      "sizes": {
        "concat": 92791,
        "dash": 97934,
        "thumbnails": 0
      },
      "duration": 1,
      "tracks": [
        {
          "type": "video",
          "codec": "H264",
          "bitrate": 2898391,
          "width": 640,
          "height": 360,
          "framerate": 29.97
        },
        {
          "type": "audio",
          "codec": "Opus",
          "bitrate": 100575,
          "channels": 2,
          "samplerate": 48000
        }
      ]
    }
  }
}

Recording Deleted

Event callback for when a recording has been deleted and removed from storage. See Recordings guide for more details on data retention.

{
  "type": "recordings",
  "event": "deleted",
  "timestamp": 1643053773667,
  "data": {
    "recordFileId": 7975,
    "tokenId": 142366,
    "streamName": "sample_stream",
    "recordedOn": 1639296462755,
    "removedOn": 1643053773659
  }
}

Recording Error

Event callback when there has been an error processing a recording.

{
  "type": "recordings",
  "event": "error",
  "timestamp": 1639296471486,
  "data": {
    "recordFileId": 7975,
    "tokenId": 142366,
    "streamName": "sample_stream",
    "recordedOn": 1639296462755
  }
}

Here is an example of the webhook body:

{
  "type": "recordings",
  "event": "deleted",
  "timestamp": 1643053773667,
  "data": {
    "recordFileId": 7975,
    "tokenId": 142366,
    "streamName": "sample_stream",
    "recordedOn": 1639296462755,
    "removedOn": 1643053773659
  }
}