Home » API Reference » Encoding Settings » Notifications » Notifications

notifications

:Array permalink

API Versions: V1, V2

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

Compatible Job Types: All

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.

Test URLs with Fetcher

If you don't have a server to post notifications to, you can use http://zencoderfetcher/.

This will create a successful notification for Fetcher to grab and post to your application.

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"
    }
  ],
  "outputs": [
    {
      "notifications": [
        "dev@example.com",
        "http://user:pass@example.com/path/to/notification/action",
        {
          "format": "xml",
          "url": "https://example.com/notifications"
        }
      ]
    }
  ]
}
      
<api_request>
  <input>s3://zencodertesting/test.mov</input>
  <notifications type="array">
    <notification>dev@example.com</notification>
    <notification>http://user:pass@example.com/path/to/notification/action</notification>
    <notification>
      <format>xml</format>
      <url>https://example.com/notifications</url>
    </notification>
  </notifications>
  <outputs type="array">
    <output>
      <notifications type="array">
        <notification>dev@example.com</notification>
        <notification>http://user:pass@example.com/path/to/notification/action</notification>
        <notification>
          <format>xml</format>
          <url>https://example.com/notifications</url>
        </notification>
      </notifications>
    </output>
  </outputs>
</api_request>