Dynamic Ingest Notifications (Legacy Ingest)

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Add Videos/Assets
Topic(s)
Notifications
Troubleshooting/Error Handling
API(s)
Dynamic Ingest API

In this topic, you will learn about Dynamic Ingest notifications, which provide information about the progress of your ingest jobs.

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 be application/x-www-form-urlencoded. Otherwise, the Content-Type will be application/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 reference id you specified for the rendition in your ingest profile.

For manifests, the profileRefId will indicate the type of the manifest:

  • HlsManifest for an HLS NG manifest
  • HdsManifest for an HDS manifest
  • DashManifest for DASH manifests (2 - one of the Manifest assets is used for consumption in the MAPI, the other is used for consumption in the CMS API)
  • SmoothIsmManifest for a Smooth manifest (2 - one of the Manifest assets is used for consumption in the MAPI, the other is used for consumption in the CMS API)
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 is TITLE, then processing of an ingested video is complete.
  • If the entityType is ASSET, 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";
?>