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
You can specify up to 10 endpoints to receive notifications by making a POST
request to https://cms.api.brightcove.com/v1/accounts/{account_id}/subscriptions
and including JSON in the request body like this:
{
"endpoint":"http://solutions.brightcove.com/bcls/di-api/di-callbacks.php",
"events":["video-change"]
}
Notifications are sent in JSON format. Here's an example:
{"timestamp":1423840514446,
"account_id":"775205503001",
"event":"video-change",
"video":"4020894387001",
"version":26}
Notification fields
Item | Description |
---|---|
timestamp |
time when the event occurred in Epoch milliseconds |
account_id |
the Video Cloud account id |
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 |
Requests to create a subscription will receive an HTTP 422 error response for the following conditions:
- The
endpoint
orevents
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 http://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html for more information.
Endpoint for notification subscriptions
/accounts/{account_id}/subscriptions
Create a new subscription
To create a new subscription, submit a POST
request with a request body including the endpoint that you want notifications delivered to and video-change
as the single item in an events
array:
{ "endpoint": "http://solutions.brightcove.com:9002", "events": [ "video-change" ] }
Get a list of your subscriptions
To get a list of all your subscriptions, send a GET
request to the subscriptions endpoint.
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 deleted
- Video metadata is changed (by the system or a user)
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.