Dynamic Ingest API notifications
You can specify one or more callback URLs to receive notifications for the results of the ingest process. The URLs you specify should be for apps than can accept POST requests. Notifications will be sent in JSON format.
Setup
Here’s an example.
- User with pub id 57838016001
- Wants to use Dynamic Ingest to upload a source video file located at https://s3.amazonaws.com/bucket/mysourcevideo.mp4
- Wants to upload an existing title in the catalog with video id 5199670523001
- Using the high-resolution profile
- Wants to receive callbacks at two endpoints located at http://host1/path1 and http://host2/path2 respectively
The DI request would look like this:
POST Request
Request body
Sample notification
Notifications are sent as POST requests with the notification in the request body as JSON [1] . Here are some sample notification:
{
"accountId": "57838016001",
"entityType": "ASSET",
"version": "1",
"status": "SUCCESS",
"videoId": "5199670523001",
"entity": "5199679295001",
"action": "CREATE",
"jobId": "699db2e5-aeb7-4765-a4a7-2cc68c7360bd"
}
{
"action": "CREATE",
"status": "SUCCESS",
"entityType": "DIGITAL_MASTER",
"videoId": "5199670523001",
"entity": "5199670523001",
"accountId": "57838016001",
"version": "1",
"jobId": "699db2e5-aeb7-4765-a4a7-2cc68c7360bd"
}
{
"entityType": "ASSET",
"status": "SUCCESS",
"action": "CREATE",
"entity": "5199680423001",
"profileRefId": "ts7",
"version": "1",
"accountId": "57838016001",
"videoId": "5199670523001",
"jobId": "699db2e5-aeb7-4765-a4a7-2cc68c7360bd"
}
{
"jobId": "699db2e5-aeb7-4765-a4a7-2cc68c7360bd",
"accountId": "57838016001",
"version": "1",
"status": "SUCCESS",
"entityType": "TITLE",
"entity": "5199670523001",
"videoId": "5199670523001",
"action": "CREATE"
}
Notes
- [1] Exception: All notifications for DRM-packaged content are returned as key/value pairs. In this case, the
Content-Type
header will beapplication/x-www-form-urlencoded
. Otherwise, theContent-Type
will beapplication/json
Notification fields
Item | Description |
---|---|
status |
will be FAILED if the ingest or creation of a rendition was not successful, SUCCESS if the request succeeded |
accountId |
the account id |
videoId |
the video id |
jobId |
the job id for the Dynamic Ingest request |
profileRefId |
For video renditions, this will be the For manifests, the
|
entity |
if it exists, the Video Cloud id of the asset that was ingested or failed (if the video object was successfully created in Video Cloud) |
entityType |
the kind of asset reported on - for example: TITLE (a video), DIGITAL_MASTER, ASSET (a rendition, captions file, or image) |
errorMessage |
an explanation of why the ingest failed if it did |
version |
a string always equal to "1" |
action |
the action that occurred - for example, CREATE |
Interpreting notifications
A notification containing "action": "CREATE"
and "status": "SUCCESS"
indicates completion of a process.
- If the
entityType
isTITLE
, then processing of an ingested video is complete. - If the
entityType
isASSET
, then a rendition, image, manifest, or WebVTT file has been successfully added to your video.
Note: a "status": "SUCCESS"
on a title indicates that processing is complete, but does not necessarily mean that it was all renditions were created successfully. To determine whether Dynamic Ingest of videos was successful, see Get Status of Dynamic Ingest Requests
Basic Sample app
Below is code for a simple logging app for Dynamic Ingest API notification. This app is written in PHP, but you can use any language, as long as the app has a public-facing URL and can handle http(s) POST requests.
You can see the log file that this app generates here.
Note: if you try to implement this app for yourself, you will need to make sure that the app has permission to write to your log file. Also remember that the log file can grow quickly - you will probably want to empty it on a regular basis.
<?php
// POST won't work for JSON data
$problem = "No errors";
try {
$json = file_get_contents('php://input');
$decoded = json_decode($json, true);
} catch (Exception $e) {
$problem = $e->getMessage();
}
// turn notification into pretty printed JSON
$notification = json_encode($decoded, JSON_PRETTY_PRINT);
$logEntry = $notification.
"\nErrors receiving notificatons: ".$problem.
"\n-------------------------------\n";
// Lastly, tell PHP where it can find the log file and tell PHP to open it
// and add the string we created earlier to it.
$logFileLocation = "di-log.txt";
$fileHandle = fopen($logFileLocation, 'a') or die("-1");
fwrite($fileHandle, $logEntry);
fclose($fileHandle);
// line below is displayed when you browse the app directly
echo "Dynamic Ingest callback app is running";
?>