Recording Hooks

Recording Lifecycle When Preserving a Stream

The recording 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.

👍

Setting up Webhooks

Review the Webhooks guide for additional details on creating and receiving webhooks.

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

  • recordFileId: unique identifier for the recording
  • tokenId
  • streamName: the publish token stream name
  • recordedOn: epoch time when the recording started

Optional:

  • removedOn: epoch time when the recording was deleted (only for deleted events)
  • metadata with 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
  }
}