NEWDolby Media Processing APIs are now the Dolby.io Media APIs Learn More >
X

Webhooks and Callbacks

Alternatives to polling for job status

As described in How It Works the Dolby.io Media APIs are asynchronous requests. While you can poll at regular intervals to determine when a job is complete, this can create unwanted network congestion and inefficiency. To solve this, Dolby.io Media APIs support both webhooks and callbacks.

  • A webhook is registered ahead of time and will be triggered at the conclusion of every job
  • A callback is specified at the time of a request and is executed only once for that particular job

This flexibility is to help support various use cases.

Webhooks

Webhooks allow you to set a URL that will receive a POST request whenever a Media API job finishes. For example, when a Media Enhance job is completed, it will send a JSON response with the completed job status.

Once a webhook is successfully registered, it is triggered for all subsequent jobs. A registered webhook configuration can be retrieved, modified or deleted at anytime.

🚧

One Webhook Per API Key

Only one webhook configuration is supported per API Key. You can create a new application from the dashboard to generate additional API Keys if you would like separate responses to an event.

To register a webhook for an application, call /media/webhooks:

# pip install requests

import requests

url = "https://api.dolby.com/media/webhooks"

payload = {"callback": {"url": "<WEBHOOK_URL>"}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "x-api-key": os.environ['DOLBYIO_API_KEY']
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
const fetch = require('node-fetch');

const url = 'https://api.dolby.com/media/webhooks';
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'x-api-key': process.env.DOLBYIO_API_KEY
  },
  body: JSON.stringify({callback: {url: '<WEBHOOK_URL>'}})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));
curl --request POST \
     --url https://api.dolby.com/media/webhooks \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-api-key: $DOLBYIO_API_KEY' \
     --data '
            {
                "callback": {
                    "url": "$WEBHOOK_URL"
                }
            }
            '

Ensure to edit the placeholder <WEBHOOK_URL> with the URL you wish the webhook payload to be sent to.

Further information and languages can be found on the API Reference page.

Notification Schema

When a webhook fires, a notification is delivered as a POST request to a service that you create. The following schema represents the notification request that is triggered when a job completes:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Webhook Notification Schema",
    "description": "Schema for the webhook notification request body.",
    "type": "object",
    "properties": {
        "job_id": {
            "type": "string",
            "description": "The ID of the job for which the notification is triggered.",
            "example": "57a60686-b223-48f1-9a06-c035b3ae3ce7"
        },
        "webhook_id": {
          "type": "string",
          "description": "The ID of the webhook that triggered the notification.",
          "example": "webhook-b945376fa616cea6f4df652150fcb85c"
        },
        "created_at": {
          "type": "string",
          "description": "Time at which the notificaiton was initiated",
          "example": "2021-05-21T09:11:31.361Z"
        },
        "path": {
          "type": "string",
          "description": "The Media API Endpoint",
          "example": "/media/enhance"
        },
        "api_version": {
          "type": "string",
          "description": "Version of the API that processed the job.",
          "example": "v1.1"
        },
       "status": {
          "type": "string",
          "description": "Status of the job.",
          "enum": [
              "Success",
              "Failed",
              "InternalError"
          ],
          "example": "Success"
        },
        "progress": {
          "type": "number",
          "description": "Progress for the job.",
          "example": 100
        },
        "result": {
          "type": "object",
          "description": "Contains result information for the processed job."
        },
        "error": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "description": "Type of the error.",
              "example": "/problems/invalid-input-file"
            },
            "title": {
              "type": "string",
              "description": "Title describing the error.",
              "example": "Input file not supported"
            },
            "detail": {
              "type": "string",
              "description": "Additional details specific to the error",
              "example": "Content less than 2.0 sec long cannot be analyzed"
            }
          },
          "required": [
            "type",
            "title"
          ]
        }
    },
    "required": [
        "job_id",
        "webhook_id",
        "created_at",
        "path",
        "status",
        "progress",
        "api_version"
    ]
}

Callbacks

To use callbacks, add the on_complete attribute to the body of any individual Media API request. The callback will be executed for that job and that job only.

For example, a request to the Media Enhance API might look like this:

{
  "input": "dlb://in.mp3",
  "output": "dlb://out.mp3",
  "on_complete": {
     "url": "https://webhook_endpoint_url",
     "body": "{\"key\": \"value\"}",
     "headers": {
        "content-type": "application/json",
        "header-example": "value example"
     }
  }
}

The url identifies the endpoint that will be called when a job completes. When the job reaches a completed state such as Success, Failed, or InternalError the Dolby.io Media API platform will trigger a request to your endpoint.

This will be a POST request and include any of the headers specified as a list of key-value pairs. The body specified when the job was initiated will also be passed as the payload. You can use this to embed a serialized JSON object or raw data as needed to support your workflow. The content-type header should correspond to the data MIME type included in the body.

Unlike webhooks, callbacks allow custom webhook URLs on a per call basis, instead of a per application basis. This flexibility allows for including a number of things such as authorization headers, correlation ids, tracking ids, customer ids, output urls, or whatever data is helpful for your use case.

👍

Tip: Tracking Usage

You may want to be able to correlate a user with a job. This would be common if you want to charge your customers for usage or to send a notification when a job is complete. To accomplish this you could keep your own records of a customer's requests with the corresponding job_id. A webhook would let you know when the job is complete. Alternatively, you could embed the user identifier in the on_complete callback so that you can send notification to that user or record the transaction in your own services.

x-job-id Header

For callbacks, the request will contain a special x-job-id header to help identify the job_id that triggered the call. This can be useful for correlation or fetching additional job details and results.

This is in addition to any headers that may have been specified in the on_complete callback.

Timeout and Retries

The request triggered by the service is set to timeout at 10s. Additionally, the service treats any response other than HTTP 2xx as a failure.

In case of timeout and failure cases described above, the request is retried one more time. If the second attempt also fails for same or different reason, the webhook/callback attempt is concluded and marked as failure.

API Reference


Did this page help you?