Live API 2.0: Notifications

Introduction

The Brightcove Live system sends notifications of various events. You can set up listeners for notifications to trigger further actions. The listener(s) can be written in any server-side language you use, and they would look for incoming POST requests, parse the JSON request body, and then take whatever action you want. Below we will see how you can request notifications.

Requesting notifications

You can request notifications by including one or more notifications fields in your Create Job request.

The value of notifications is an array of notification destination objects. Each notification object requires the following fields:

• url (required) - The URL endpoint where notifications will be sent
• subscription_type (required) - The type of event to subscribe to. Supported values:
  • state_change - Notifications for job state changes
  • error - Notifications for errors

A notification will be sent to the destination you specify when the subscribed event occurs.

Here are some examples:

Notifications for a Live job

{
  "name": "My Live Stream",
  "type": "channel",
  "region": "us-west-2",
  "notifications": [
    {
      "url": "https://example.com/notifications",
      "subscription_type": "state_change"
    }
  ],
  "input": {
    "protocol": "rtmp"
  },
  "outputs": {
    "video": [
      {
        "label": "720p",
        "height": 720,
        "width": 1280,
        "bitrate": 3000000,
        "codec": "h264"
      }
    ],
    "audio": [
      {
        "label": "default",
        "codec": "aac",
        "bitrate": 128000
      }
    ]
  }
}

Retry strategy

In the event of a failed request to send a notification, the default retry strategy is to retry 50 times with an exponential delay between attempts.

          max_retry_times = 50
          delay_delta_s = 5
          next_retry = now_s + retry_count * delay_delta_s

Notification payload structure

When a state_change event occurs, the notification payload includes a code field that provides more specific information about the type of state change. The notification payload structure includes the following fields:

• resource_id - The ID of the live job
• resource_type - The type of resource (e.g., "live-job")
• code - A code indicating the specific type of state change (see table below)
• type - The event type (e.g., "state_change")
• message - A human-readable message describing the state change
• timestamp - The timestamp when the event occurred

Notification code values

The code field in the notification payload can have the following values:

Sample notification payloads

Here are examples of notification payloads for state_change events:

Job created notification:

{
  "resource_id": "6384174165112",
  "resource_type": "live-job",
  "code": "JOB_CONFIGURED",
  "type": "state_change",
  "message": "Job created",
  "timestamp": 1761625844857
}

Encoder connected notification:

{
  "resource_id": "6384174165112",
  "resource_type": "live-job",
  "code": "INGEST_CONNECTED",
  "type": "state_change",
  "message": "ingest endpoint ingest is connected",
  "timestamp": 1760760241839
}

Handling notifications

To receive notifications, you simply need an app that can receive HTTP/HTTPS POST requests. The app can then parse the JSON notifications and do whatever you want based on their contents.