CMS API Notifications

In this topic, you will learn about CMS API notifications. The CMS API provides notifications of changes to the videos in your account, whether made by an account user or the Video Cloud system.

Overview

You can receive notifications when video-change events occur in your video library. Notifications will be sent to the URL you specify, which should point to an application capable of handling HTTP POST requests.

Authentication

Like all requests to the CMS API, requests to set up or list notification subscriptions must be authenticated using an access token. The client credentials used to get the access token must have permissions for video-cloud/notifications/all (CMS->Notifications if you use the Studio UI to create the credentials.)

Setup

To create a new subscription, submit a POST request to https://cms.api.brightcove.com/v1/accounts/{{account_id}}/subscriptions with a request body including the endpoint that you want notifications delivered to and video-change or master-video-change as the single item in an events array. You can specify up to 10 endpoints per event to receive notifications.

The available events for video-change are for your video library, and now, events for master-video-change are for changes in the assets of a dynamic delivery master video that will eventually be reflected in your shared video.

For video-change events

{
        "endpoint":"https://solutions.brightcove.com/bcls/di-api/di-callbacks.php",
        "events":["video-change"]
        }

For master-video-change events

{
        "endpoint":"https://solutions.brightcove.com/bcls/di-api/di-callbacks.php",
        "events":["master-video-change"]
        }

Notifications are sent in JSON format. Here's an example for video-change events:


{
    "account_id": "account_id",
    "updated_by": {
    "ip": "x.x.x.x",
    "type": "internal",
    "user_agent": "BoltIngestWorker/df3979c"
    },
    "action": "UPDATE",
    "video": "video_id",
    "event": "video-change",
    "version": 2,
    "timestamp": 1719930805071
}

And an example for master-video-change looks like this:


{
    "account_id": "account_which_has_the_video_shared",
    "master_account_id": "account_which_is_the_original_owner_of_the_video",
    "updated_by": {
    "ip": "x.x.x.x",
    "type": "internal",
    "user_agent": "ingest/imageprocessor"
    },
    "master_video_id": "video_id_from_the_original_owner_of_the_video",
    "action": "update",
    "video": "video_id_from_the_video_shared_account",
    "event": "master-video-change",
    "timestamp": 1720647010151
}

Notification fields

Item Description
timestamp time when the event occurred in Epoch milliseconds
account_id the Video Cloud account id
master_account_id the Only for master-video-change events: The id of the master video who made the update in the assets shared with the affiliate video.
master_video_id the Only for master-video-change events: The id of the Video Cloud master account for the master video.
event the type of event - currently this will always be video-change
video the video ID
version the version of the video - each set of change events increments the video version - for example, creation of a new set of renditions would constitute a set of change events
action[1-1] the action that was performed - one of the following:
  • UPDATE - an asset was updated
  • CREATE - an asset was created
  • TRIGGERED_MANUAL - a notification was triggered by an internal Brightcove application
  • DELETE - an asset was deleted
  • updated_by[1-1] an object containing information about who performed the action, if available; the object properties are:
  • email - the user's email address
  • id- the Video Cloud system id for the user
  • type - the type of update:
    • user - a user in Studio
    • api-key - a user via the API
    • internal - a Brightcove system or user
  • Requests to create a subscription will receive an HTTP 422 error response for the following conditions:

    • The endpoint or events field is missing from the request body
    • The events field value is not a list (array)
    • The subscription defined already exists
    • You already have 10 subscriptions to this event

    Notification failures

    The notification system treats any 4xx or 5xx return from the customer server as a retry-able failure. Failing callbacks will be retried up to 20 times, with an exponentially increasing delay between subsequent callbacks. The first few retries will happen within minutes of the initial callback attempt. If the callback continues failing, and we get all the way out to the 20th retry, the retry delay will be a few days.

    Firewalls

    In case your organization has a strict policy regarding sources of incoming traffic through your firewall, we allow the AWS us-east-1/Virginia IPs. This is subject to change, so all AWS IPs should be whitelisted. See https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html for more information.

    Endpoint for notification subscriptions

          /accounts/{{account_id}}/subscriptions
          
        

    Get a list of your subscriptions

    To get a list of all your subscriptions, send a GET request to the subscriptions endpoint:.

    /accounts/{{account_id}}/subscriptions
        

    Get or Delete a single subscription

    Use the following endpoint to get or delete a single subscription:

    Endpoint

    /accounts/{{account_id}}/subscriptions/{subscription_id}

    A GET request will retrieve the subscription. A DELETE request will delete the subscription. You cannot update a subscription at this time. If you want to modify a subscription, you will need to delete it and create a new one.

    What triggers notifications?

    video-change events are triggered by any change in the video metadata. This includes any change to the video made in Studio or through a CMS API write method. There are also system events that will trigger video-change events.

    Changes that will trigger an event include:

    • A video is created
    • Ingestion of video or asset file starts
    • Ingestion of video or asset file is completed
    • Encoding of a new rendition finishes
    • A poster image is created
    • A thumbnail image is created
    • A video is activated or deactivated
    • A video is deleted
    • Video metadata is changed (by the system or a user)
    • master-video-change events are triggered by updates in the assets of a master video, which makes them only available for sharing.

      Changes that will trigger this event include:

      • Ingested assets are added to the master video
      • Ingested assets are replaced/retranscoded in the master video

    Notes

    Retranscoding a video will not trigger a video-change event unless the resulting rendition set is different.

    There are system events that occur after a video is deleted, so you will receive notifications about a video after deleting it.

    What will not trigger a video-change event is a change to a video asset that does not change the video metadata. For example, if you replace a remote text track file or image, but the URL recorded in the video metadata remains the same, no video-change event will occur, and no notification will be sent.

    Deletion of assets in a master video will not trigger a master-video-change event. When assets are removed in a video it’s because the video is being deleted, and sharing already handles the deletion process for affiliate videos.