Home » Guides » Getting Started » Getting Notifications When Videos Are Finished

permalink Getting Notifications When Videos Are Finished

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

API V1 Note: Job-level notifications are not supported.

API V1 Note: Content-Type is not set unless notification is specified.

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"
          ]
        }
      ]
    }
  
    
      93h630j1dsyshjef620qlkavnmzui3
      s3://bucket-name/file-name.avi</input>
      
        http://user:password@example.com/zencoder
        admin@example.com
      
      
        
          
          s3://output-bucket/web.mp4
          512x384
          
            http://user:password@example.com/zencoder
            admin@example.com
          
        
        
          
          s3://output-bucket/iphone.m4v
          480x320
          
            
              xml
              http://example.com/zencoder1
            
            
              xml
              http://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 succesfully connect to the target server when sending a notification, the notification will be queued to try again. The notification will be attempted up to 25 times, with the delay between attempts doubling each time.

HTTP Notifications - API Version 2

Beginning in API version 2 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"
    }
  }
  
    
    
      
        
          16
          48000
          29.97
          2
          5055
          87
          h264
          mpeg4
          62625
          aac
          93
          
          30
          235316
          6
          finished
          ftp://example.com/file.mp4
          7f106918e02a69466afa0ee014172496
          
            
              
                
                  ftp://example.com/images/123.png
                  PNG
                  1273573
                  1280x720
                
              
              
            
          
        
        
          16
          48000
          29.97
          2
          5055
          87
          h264
          mpeg4
          62625
          aac
          93
          
          30
          235316
          6
          finished
          ftp://example.com/file.mp4
          7f106918e02a69466afa0ee014172496
          
            
              
                
                  ftp://example.com/images/123.png
                  PNG
                  1273573
                  1280x720
                
              
              
            
          
        
      
      
        false
        2011-09-27T19:14:24Z
        
        2011-09-27T19:15:01Z
        2011-09-27T19:14:24Z
        172153
        finished
      
      
        16
        48000
        29.97
        2
        5038
        148
        h264
        mpeg4
        100149
        aac
        155
        30
        172151
        finished
        7
        7f106918e02a69466afa0ee014174143
      </input>
    
  

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"
    }
  }
  
    
    
      
        16
        48000
        29.97
        2
        5055
        87
        h264
        mpeg4
        62625
        aac
        93
        
        30
        235316
        6
        finished
        ftp://example.com/file.mp4
        7f106918e02a69466afa0ee014172496
        
          
            
              
                ftp://example.com/images/123.png
                PNG
                1273573
                1280x720
              
            
            
          
        
      
      
        false
        2011-09-27T19:14:24Z
        
        2011-09-27T19:15:01Z
        2011-09-27T19:14:24Z
        172153
        finished
      
      
        16
        48000
        29.97
        2
        5038
        148
        h264
        mpeg4
        100149
        aac
        155
        30
        172151
        finished
        7
        7f106918e02a69466afa0ee014174143
      </input>
    
  

HTTP Notifications - API Version 1

The notification API request is sent from Zencoder to your server as a POST to the notification URL, and is either JSON or XML containing two or three values. The first is a Job ID. This ID matches the ID you received when you submitted the initial job request. Second is the state – either ‘processing', ‘finished', ‘failed', or ‘cancelled'. If the output was assigned a label the notification will also contain the output label you supplied when the job was initially created.

Finished Job

     
    {"job":
      {"state":"finished","id":1234},
      "output":{
        "label":"web",
        "url":"http://example.com/file.mp4",
        "state":"finished",
        "id":12345
      }
    }
  
    
      
        finished
        1234
      
      
        finished
        
        12345
        http://example.com/file.mp4
      
    
  

Failed Job

    {"job":
      {"state":"failed","id":1234},
      "output":{
        "label":"web",
        "url":"http://example.com/file.mp4",
        "state":"failed",
        "id":12345
      }
    }
  
    
      
        failed
        1234
      
      
        failed
        
        12345
        http://example.com/file.mp4