Notifications Settings

This topic contains details for encoding settings related to notifications.

Overview

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

  • We can send a HTTP POST request to your application with the details.
  • We can send an email.
  • 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.
  • You can check the Zencoder Dashboard for job status.
  • You can check job status via a Job show API request.

The first two - outgoing HTTP or email notifications - are triggered by adding notification options to your Job create API request.

Notes:

  • Notifications are limited to 5 per output and job. Output notifications do not count towards the job total. Contact us if you need more.
  • Notification payloads may repeat notifications for jobs. You should parse the payload body by job ID then state.
  • Notification handlers on servers built on HTTP2 are not currenly supported. Notifications sent to HTTP2 servers may fail to be delivered without returning any error.

notifications

notifications:Array

API Versions: V2

Valid Values: An array of notification strings (valid email addresses or URLs), or hashes of url and format.

Compatible Job Types: VOD

Description:

Specify one or more HTTP URLs or email addresses to notify with a webhook when a job or output is complete.

For HTTP notifications, 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 a status – either ‘finished’, ‘failed’, or ‘cancelled’. If a job contains multiple outputs, this notification also contains the output label you supplied when the job was initially created.

HTTP notifications will send JSON or XML (depending on the requested format).

Notification Contents vary depending on the API version used.

If Zencoder is unable to successfully connect to the target server when sending a notification, the notification will be queued to try again. The retry schedule is covered in the notifications guide.

Authorization and Security

For authenticated HTTP notifications, include a username and password in the notification URL using this syntax: https://username:password@www.example.com/path/to/notification/action

For HTTPS, simply specify a URL using https:// will force the notification to be sent securely using SSL.

Note: API V1 only supports output notifications, not job notifications.

{
  "input": "s3://zencodertesting/test.mov",
  "notifications": [
    "dev@example.com",
    "http://user:pass@example.com/path/to/notification/action",
    {
      "format": "xml",
      "url": "https://example.com/notifications.html"
    }
  ],
  "outputs": [
    {
      "notifications": [
        "dev@example.com",
        "http://user:pass@example.com/path/to/notification/action",
        {
          "format": "xml",
          "url": "https://example.com/notifications.html"
        }
      ]
    }
  ]
}

See Also: url, format, and headers

url

url:String

API Versions: V2

Parent: notifications

Valid Values: A valid HTTP or HTTPS URL to notify, optionally including HTTP Auth credentials

Compatible Job Types: VOD

Examples:

  • https://username:password@example.com/notification/path
  • http://example.com/notification-handler.php

Description:

A URL to notify when a job is complete.

Use the url option when specifying notifications as a hash, including a format. If you don't need to specify a format, you can simply include the URL as an item in the notifications array.

For authenticated HTTP notifications, include a username and password in the notification URL using this syntax: https://username:password@www.example.com/path/to/notification/action.

For HTTPS, simply specify a URL using https:// so a notification would be sent securely using SSL.

Notification Contents vary depending on the API version used.

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.

Authorization and Security

For authenticated HTTP notifications, include a username and password in the notification URL using this syntax: https://username:password@www.example.com/path/to/notification/action

For HTTPS, simply specify a URL using https:// will force the notification to be sent securely using SSL.

Notes: API V1 only supports output notifications, not job notifications.

{
  "input": "s3://zencodertesting/test.mov",
  "notifications": [
    {
      "url": "https://example.com/notifications.html"
    }
  ],
  "outputs": [
    {
      "notifications": [
        {
          "url": "https://example.com/notifications.html"
        }
      ]
    }
  ]
}

See Also: notifications, format, and headers

format

format:String

API Versions: V2

Parent: notifications

Valid Values: json or xml

Compatible Job Types: VOD

Example: json

Description:

A format and content type for notifications.

By default, HTTP notifications are in JSON, with an HTTP Content-Type of application/json.

For XML notifications, set format to 'xml'. This will return notifications in XML format, with an HTTP Content-Type of application/xml.

Note: API V1 notifications do not include an HTTP Content-Type unless you specify a format.

{
  "input": "s3://zencodertesting/test.mov",
  "notifications": [
    {
      "format": "xml",
      "url": "https://example.com/notifications.html"
    }
  ],
  "outputs": [
    {
      "notifications": [
        {
          "format": "xml",
          "url": "https://example.com/notifications.html"
        }
      ]
    }
  ]
}

See Also: notifications, format, and headers

headers

headers:Hash

API Versions: V2

Parent: notifications

Valid Values: Keys must start with a letter and can contain letters, numbers, and -. Values can contain any string.

There is a length limit of 100 characters for each notification header.

Compatible Job Types: VOD

Example: {'Accept': 'application/json', 'Internal-Id': '12345'}

Description:

By default, HTTP notifications are sent with an HTTP Content-Type, along with a User-Agent. If your application requires additional headers, they can be specified here.

The header is set as the key of the hash, and its value is the value of the hash.

{
  "input": "s3://zencodertesting/test.mov",
  "notifications": [
    {
      "format": "json",
      "url": "https://example.com/notifications.html",
      "headers": {
        "Accept": "application/json",
        "Internal-Id": "12345"
      }
    }
  ],
  "outputs": [
    {
      "notifications": [
        {
          "format": "json",
          "url": "https://example.com/notifications.html",
          "headers": {
            "Accept": "application/json",
            "Internal-Id": "12345"
          }
        }
      ]
    }
  ]
}

See Also: notifications, url, and format

event

event:String

API Versions: V2

Parent: notifications

Valid Values: first_segment_uploaded, seamless_playback

Compatible Job Types: VOD

Example: {'event': 'seamless_playback'}

Description:

Live outputs have additional notification events corresponding to the progress of the file.

Notifications can be sent when the first segment of a Live output has been uploaded and when enough segments have been uploaded to enable seamless playback.

Event does not apply to regular job and output notifications, only to those for Live outputs.

{
  "input": "s3://zencodertesting/test.mov",
  "outputs": [
    {
      "live_stream": true,
      "type": "segmented",
      "notifications": [
        {
          "url": "http://zencoderfetcher/notifications.html",
          "event": "seamless_playback"
        }
      ]
    }
  ]
}

See Also: notifications, url, and format