Notifications

Encoding.com offers a robust notification system via our API that provides update notifications on nearly every aspect of a job.

<?xml version="1.0"?>
<query>
    <!-- Main params -->
    <userid><<id>></userid> <!-- required -->
    <userkey><<key>></userkey> <!-- required -->
    <action>[Action]</action> <!-- required -->
    <source>[SourceFile]</source> <!-- required -->
    <notify_format>[xml|json]</notify_format>
    <notify>[NotifyURL]</notify>
    <notify_encoding_errors>[NotifyEncodingErrorURL]</notify_encoding_errors>
    <notify_upload>[NotifyUploadURL]</notify_upload>
    <notify_upload_extended>[yes|no]</notify_upload_extended>
    <notify_live_start>[NotifyLiveStartedURL]</notify_live_start>
    <qc_notify>[QCNotifyURL]</qc_notify>
    <extended_notify>[yes|no]</extended_notify>
    <format> <!-- required -->
        <!-- Format params -->
    </format> 
</query>
{
    "query": {
        "userid": "<<id>>", // required
        "userkey": "<<key>>", // required
        "action": "[Action]", // required
        "source": "[SourceFile]", // required
        "notify_format": "[xml|json]",
        "notify": "[NotifyURL]",
        "notify_encoding_errors": "[NotifyEncodingErrorURL]",
        "notify_upload": "[NotifyUploadURL]",
        "notify_upload_extended": "[yes|no]",
        "notify_live_start": "[NotifyLiveStartedURL]",
        "qc_notify": "[QCNotifyURL]",
        "extended_notify", "[yes|no]",
        "format": [ // required
             {
                 // Format params
             }
        ]
    }
}

URL Format

Type

Format

HTTP(s) URL

https://domain.tld/path-to-endpoint

AWS API Gateway

https://[Key:Secret]:[ApiID].execute-api.[Region].amazonaws.com/[StageName]/

AWS SNS Topic

arn:aws:sns:[Region]:[AWSAccountID]:[TopicName]

Email

[email protected]

🚧

For AWS API Gateway

Credentials in the URL can be omitted. In this case, we will use our credentials to authenticate call to your API Gateway.

🚧

For Email

You can provide several email addresses separated by a comma.
E.g. [email protected], [email protected]

Amazon SNS Configuration

Here are a few steps that will help you to set up Amazon SNS topics.

  1. Go to the AWS SNS console
  2. Select region
  3. Create new Topic
  4. Set Publish access for all aws customers or for:
    - AWS user: 1a85ad8fea02b4d948b962948f69972a72da6bed800a7e9ca7d0b43dc61d5869
    - Account ID: "AWS": "456240961796"
    - ARN ID: arn:aws:iam::456240961796:root
    JSON policy:{ "Sid": "__console_pub_0", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::456240961796:root" }, "Action": "SNS:Publish", "Resource": "%TopicARN%" }
  5. Add subscriptions. Don't forget to confirm these subscriptions.

More information about how to use Amazon SNS you can read in the official documentation.

👍

Note

You can use any supported region for the Amazon SNS topic. It isn't a requirement to be set the same as the media processing region.
Supported regions:

  • ap-east-1
  • ap-northeast-1
  • ap-northeast-2
  • ap-south-1
  • ap-southeast-1
  • ap-southeast-2
  • ca-central-1
  • eu-central-1
  • eu-north-1
  • eu-west-1
  • eu-west-2
  • eu-west-3
  • fips-us-east-1
  • fips-us-east-2
  • fips-us-west-1
  • fips-us-west-2
  • me-south-1
  • sa-east-1
  • us-east-1
  • us-east-2
  • us-west-1
  • us-west-2

Parameters

Parameter

Description

notify_format

Can be XML (default) or JSON – defines response format.

notify

Request to be notified about job results.
This field may be specified for AddMedia and AddMediaBenchmark actions.

notify_encoding_errors

Notify if media finishes with encoding errors.

notify_upload

Notify when media uploaded to the specified destination.

notify_upload_extended

Same as above with output parameters included.

notify_live_start

Notify when live task is ready for playback.

qc_notify

Notify when QC processing finished for each output format.

extended_notify

Add output_json and audio_validation data to the Notification response body.

🚧

When using the notify_upload parameter...

For advanced_hls, advanced_mss, and advanced_dash outputs, a notification for each stream will be sent.

If the <notify_upload_extended /> parameter is set to yes, output parameters will be included with notification callback(s). Please note that this feature doesn’t currently work with multibitrate output formats).