Getting Notifications When Videos Are Finished

This topic shows you how to get notifications when your Zencoder job is complete.

Overview

After a job or an output file is complete, you can find out about it in several ways.

  • We can POST an HTTP request to your application with the details.
  • You can request your notifications using a third-party tool such as ngrok. This is useful when you are developing locally and Zencoder can’t reach your development server.
  • We can send an email.
  • You can check the Zencoder Dashboard for job status.

Get HTTP/Email notifications

To receive HTTP or email notifications, add Notification options to your API request, like this:

{
  "api_key": "93h630j1dsyshjef620qlkavnmzui3",
  "input": "s3://bucket-name/file-name.avi",
  "notifications": [
  "http://user:password@example.com/zencoder",
  "admin@example.com"
  ],
  "outputs": [
  {
      "label": "web",
      "url": "s3://output-bucket/web.mp4",
      "size": "512x384",
      "notifications": [
      "http://user:password@example.com/zencoder",
      "admin@example.com"
      ]
  },
  {
      "label": "iphone",
      "url": "s3://output-bucket/iphone.m4v",
      "size": "480x320",
      "notifications": [
      {"format": "xml", "url": "http://user:password@example.com/zencoder1"},
      {"format": "json", "url": "http://user:password@example.com/zencoder2"},
      "http://example.com/zencoder3",
      "admin@example.com"
      ]
  }
  ]
}

In this example, when the first output file is completed, two notifications would be sent:

  • Email to admin@example.com with information about the output and the input/job.
  • HTTP POST to http://user:password@example.com/zencoder with a Content-Type header set to 'application/json' with information about the output and the input/job.

When the second output file is complete, four more notifications would be sent:

  • HTTP POST to http://example.com/zencoder1 with a Content-Type header set to 'application/xml' with information about the output and the input.
  • HTTP POST to http://example.com/zencoder2 with a Content-Type header set to 'application/json' with information about the output and the input/job.
  • Email to admin@example.com with information about the output and the input/job.
  • HTTP POST to http://example.com/zencoder3 with a Content-Type header set to 'application/json' with information about the output and the input/job.

When the job is completed, two more notifications would be sent:

  • Email to admin@example.com with information about the output and the input.
  • HTTP POST to http://user:password@example.com/zencoder with a Content-Type header set to 'application/json' with information about the output and the input.

Note: If Zencoder is unable to successfully connect to the target server when sending a notification, the notification will be queued to try again. The notification will be attempted up to 20 times, with the delay between attempts doubling each time.

HTTP Notifications

Notifications contain rich content with much more information about the job and input and output files. The body of the notification can contain JSON or XML. If uploads fail, notifications will also contain information about errors and backup servers used.

Job Notification Example

{
  "outputs":[
  {
      "height":120,
      "audio_sample_rate":8000,
      "frame_rate":8.0,
      "channels":"1",
      "duration_in_ms":1920,
      "video_bitrate_in_kbps":70,
      "video_codec":"h264",
      "format":"mpeg4",
      "audio_codec":"aac",
      "label":null,
      "file_size_in_bytes":17938,
      "width":160,
      "audio_bitrate_in_kbps":9,
      "id":235314,
      "total_bitrate_in_kbps":79,
      "state":"finished",
      "url":"ftp://example.com/file.mp4",
      "md5_checksum":"7f106918e02a69466afa0ee014172496",
      "thumbnails": [
      {
          "label":"poster",
          "images":
          [
          {
              "url": "ftp://example.com/images/123.png",
              "format": "PNG",
              "file_size_bytes": 1273573,
              "dimensions": "1280x720"
          }
          ]
      }
      ]
  },
  {
      "height":120,
      "audio_sample_rate":8000,
      "frame_rate":8.0,
      "channels":"1",
      "duration_in_ms":1920,
      "video_bitrate_in_kbps":70,
      "video_codec":"h264",
      "format":"mpeg4",
      "audio_codec":"aac",
      "label":null,
      "file_size_in_bytes":17938,
      "width":160,
      "audio_bitrate_in_kbps":9,
      "id":235314,
      "total_bitrate_in_kbps":79,
      "state":"finished",
      "url":"ftp://example.com/file.mp4",
      "md5_checksum":"7f106918e02a69466afa0ee014172496",
      "thumbnails": [
      {
          "label":"poster",
          "images":
          [
          {
              "url": "ftp://example.com/images/123.png",
              "format": "PNG",
              "file_size_bytes": 1273573,
              "dimensions": "1280x720"
          }
          ]
      }
      ]
  }
  ],
  "job":{
      "created_at":"2011-09-27T04:20:10Z",
      "pass_through":null,
      "updated_at":"2011-09-27T04:21:18Z",
      "submitted_at":"2011-09-27T04:20:10Z",
      "id":172151,
      "state":"finished"
  },
  "input":{
      "height":120,
      "audio_sample_rate":8000,
      "frame_rate":8.0,
      "channels":"1",
      "duration_in_ms":1552,
      "video_bitrate_in_kbps":32,
      "video_codec":"mpeg4",
      "format":"mpeg4",
      "audio_codec":"aac",
      "file_size_in_bytes":13960,
      "width":160,
      "audio_bitrate_in_kbps":9,
      "id":172149,
      "state":"finished",
      "total_bitrate_in_kbps":41,
      "md5_checksum":"7f106918e02a69466afa0ee014174143"
  }
}

Output Notification Example

{
  "output":{
      "height":120,
      "audio_sample_rate":8000,
      "frame_rate":8.0,
      "channels":"1",
      "duration_in_ms":1920,
      "video_bitrate_in_kbps":70,
      "video_codec":"h264",
      "format":"mpeg4",
      "audio_codec":"aac",
      "label":null,
      "file_size_in_bytes":17938,
      "width":160,
      "audio_bitrate_in_kbps":9,
      "id":235314,
      "total_bitrate_in_kbps":79,
      "state":"finished",
      "url":"ftp://example.com/file.mp4",
      "md5_checksum":"7f106918e02a69466afa0ee014172496",
      "thumbnails":
      [
      {
          "label":"poster",
          "images":
          [
          {
              "url": "ftp://example.com/images/123.png",
              "format": "PNG",
              "file_size_bytes": 1273573,
              "dimensions": "1280x720"
          }
          ]
      }
      ]
  },
  "job":{
      "created_at":"2011-09-27T04:20:10Z",
      "pass_through":null,
      "updated_at":"2011-09-27T04:21:18Z",
      "submitted_at":"2011-09-27T04:20:10Z",
      "id":172151,
      "state":"finished"
  },
  "input":{
      "height":120,
      "audio_sample_rate":8000,
      "frame_rate":8.0,
      "channels":"1",
      "duration_in_ms":1552,
      "video_bitrate_in_kbps":32,
      "video_codec":"mpeg4",
      "format":"mpeg4",
      "audio_codec":"aac",
      "file_size_in_bytes":13960,
      "width":160,
      "audio_bitrate_in_kbps":9,
      "id":172149,
      "state":"finished",
      "total_bitrate_in_kbps":41,
      "md5_checksum":"7f106918e02a69466afa0ee014174143"
  }
}

Sample notification handler

Below is a simple PHP app for handling notifications.

getMessage();
      $notification = $json;
  }

  $logEntry = $notification."\n \n";

  // 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 = "live-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 "Zencoder callback app is running";
  ?>