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>[UserID]</userid> <!-- required -->
    <userkey>[UserKey]</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>
    <qc_start_notify>[QCStartNotifyURL]</qc_start_notify>
    <extended_notify>[yes|no]</extended_notify>
    <notify_body_format>[form_urlencoded|raw]</notify_body_format>
    <format> <!-- required -->
        <!-- Format params -->
    </format> 
</query>
{
    "query": {
        "userid": "[UserID]", // required
        "userkey": "[UserKey]", // 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]",
        "qc_start_notify": "[QCStartNotifyURL]",
        "extended_notify", "[yes|no]",
        "notify_body_format", "[form_urlencoded|raw]",
        "format": [ // required
             {
                 // Format params
             }
        ]
    }
}

URL Format

TypeFormat
HTTP(s) URLhttps://domain.tld/path-to-endpoint
AWS API Gatewayhttps://[Key:Secret]:[ApiID].execute-api.[Region].amazonaws.com/[StageName]/
AWS SNS Topicarn:aws:sns:[Region]:[AWSAccountID]:[TopicName]
Emailmailto:[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. mailto:[email protected], [email protected]

🚧

For HTTP(s) URLs

HTTP(s) notification requests could come from these IP ranges: "34.193.0.100/32" and "100.24.75.0/32"

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

HTTP(s) Notification Signature

For each HTTP(s) notification we add special HTTP header VG-Signature which contains at least 2 comma separated parameters (in future we may add more):

  • t – timestamp
  • v1 – hash-based message authentication code (HMAC) with SHA-256
VG-Signature: t=[TimeStamp],v1=[Signature]

To verify signature, you should complete the following steps:

  • Split the header using the , character as the separator to get a list of elements. Split each element using the = character as the separator to get a prefix and value pair. The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature.
  • Prepare the signed_message string. The signed_message string is created by concatenating:
    • the timestamp (t value)
    • the . character
    • request body
  • Compute an HMAC with the SHA256 hash function. Use your api key as the key, and use the signed_message string as the message.
  • Compare the signature in the header to the expected signature.

You may also compute the difference between the current timestamp and the received timestamp, and decide if the difference is within your tolerance.

Implementation samples

const {createHmac} = require('crypto');
function verify_signature (header, request) {
    const [[,timestamp],[,signature]] = header.split(',').map(p => p.split('='))
    const signed_message = `${timestamp}.${request}`;
    const hmac = createHmac('sha256', '[UserKey]');
    const expected_signature = hmac.update(signed_message).digest('hex');
    return expected_signature === signature;
}
const header = 't=[timestamp],v1=[signature]';
const request = '[HTTPRequestBody]';

console.log(verify_signature(header, request) ? 'ok' : 'fail');
function verify_signature (string $header, string $request)
{
    [[$t, $timestamp], [$sgn, $signature]] = array_map(
        fn ($p) => explode('=', $p),
        explode(',', $header)
    );
    $signed_message = sprintf('%s.%s', $timestamp, $request);
    $expected_signature = hash_hmac(
        'sha256',
        $signed_message,
        '[UserKey]'
    );
    return $expected_signature === $signature;
}
$header = 't=[timestamp],v1=[signature]';
$request = '[HTTPRequestBody]';

echo verify_signature($header, $request) ? 'ok' : 'fail';
import hmac
import hashlib
def verify_signature(header, request):
    ts, sgn, * other = header.split(',')
    t, timestamp, * other = ts.split('=');
    v, signature, * other = sgn.split('=');
    signed_message = '{}.{}'.format(timestamp,request)
    expected_signature = hmac.new(
        bytes("[UserKey]", 'utf-8'), 
        bytes(signed_message, 'latin-1'), 
        hashlib.sha256
    ).hexdigest()
    return expected_signature == signature

header = "t=[timestamp],v1=[signature]"
request = "[HTTPRequestBody]"

print("ok" if verify_signature(header, request) else "fail")

Parameters

ParameterDescriptionAllowed ValuesDefault Value
notify_formatCan be XML (default) or JSON – defines response format.xml, jsonxml
notifyRequest to be notified about job results.
This field may be specified for AddMedia and AddMediaBenchmark actions.
• Valid URL
• Email
• SNS URI
none
notify_encoding_errorsNotify if media finishes with encoding errors.• Valid URL
• Email
• SNS URI
none
notify_uploadNotify when media uploaded to the specified destination.• Valid URL
• Email
• SNS URI
none
notify_upload_extendedSame as above with output parameters included.yes, nono
notify_live_startNotify when live task is ready for playback.• Valid URL
• Email
• SNS URI
none
qc_notifyNotify when QC processing finished for each output format.• Valid URL
• Email
• SNS URI
none
qc_start_notifyNotify when QC processing started for each output format.• Valid URL
• Email
• SNS URI
none
extended_notifyAdd output_json and audio_validation data to the Notification response body.yes, nono
notify_body_formatCan be either raw (where the body contains raw xml/json "as is") or form_urlencoded. The Content-Type header will be set accordingly.raw, form_urlencodedform_urlencoded

🚧

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