Live API 2.0: Notifications

This topic show how to set up notifications for Live API 2.0 jobs.

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 the outputs your Create Job request.

The value of notifications is an array of notification destination objects. You can use an object with following options: {"url": "http://callmeonstatechange.com/jobid", "credential_id": "reference_to_your_credentials", "subscription_type": "state_change", "method": "POST"}. A notification will be sent to the destination you specify when the output changes its state.

Here are some examples:

Notifications for a Live job

{
    "live_stream": true,
    "region": "us-west-2",
    "reconnect_time": 20,
    "notifications": [
      {"url": "https://httpbin.org/post/URLB",
      "credentials": "reference_to_your_credentials",
      "event": "state_changed",
      "method": "POST"}
      ],
    "outputs": [
    {
        "label": "hls360p",
        "live_stream": true,
        "height": 360,
        "video_bitrate": 650,
        "segment_seconds": 6
    }]
}

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

Events

Below are the events of a job lifecycle you can listen for.

state_changed - the state of the live job changed; see the table below for details

The state_changed will notify on the following states described in the table below

Live Job States
State	Description
JOB States (reported in notifications as `state`)
`error`	An error has occurred; the job will not be processed.
`standby`	(Only applicable to Static Entry Point [SEP] jobs.) The job is allocated and ready for activation.
`processing`	The encoder is connected and the job is available for playback.
`disconnected`	The encoder has disconnected and the streaming worker is waiting for a reconnection.
`cancelling`	The job has been cancelled and the worker is stopping the job and will NOT process any pending VOD outputs.
`finishing`	The encoder has been disconnected for more than `reconnect_time`, and streaming worker is stopping the jobs and creating any associated VOD outputs.
`cancelled`	The job has been cancelled successfully.
`finished`	The job has finished successfully.
`failed`	The job has stopped as a result of a system error.

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.

Limited Availability - Do not share this document