support Contact Support | system status System Status
Page Contents

    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: 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.

    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: V1, V2

    Parent: notifications

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

    Compatible Job Types: All

    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: V1, V2

    Parent: notifications

    Valid Values: json or xml

    Compatible Job Types: All

    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: All

    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: All

    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


    Page last updated on 28 Sep 2020