Update 5/22: Dolby.io now officially has a Zapier Integration! Read more here.

When working with a Dolby.io Media job, one way to see if the job is done is to poll for its status, running the API to check periodically. While this works for small scale applications, it is a highly inefficient workflow that can easily jam up processing bandwidth, eat up API calls (if those APIs are limited by call volume), and are limited to the rate limiting of the API being used.

Solving Polling with Dolby.io Webhooks

Fortunately, there is another solution: Webhooks. In short, webhooks are a way for the job to tell you when its done, instead of having to check yourself. It does this by using HTTP requests, typically PUSH, to send a payload to a predefined URL. This is useful not only for avoiding polling, but also in providing useful context for each individual job from looking at the payload details. This can include fields such as which job has completed, if it was successful or failed, and any error descriptions.

For Dolby.io Media APIs, we use webhooks to create processes for when a job has been completed, such as an Enhance or an Analyze, to prevent bottlenecks in the workflow to use the data that was just created immediately. Let’s walk through how to get started using Webhooks with Media APIs using Slack and Zapier as destinations for our data.

Choosing the Dolby.io Webhook Destination

Before we create the webhook, we need somewhere to send the payload to in the first place. There are a large number of options for this. A common option is to use your own web server, such as ExpressJS or Django, to receive a POST request and handle it appropriately. Alternatively, you could use third party applications, such as an AWS Lambda, a Google Cloud Function, or an Azure Automation to receive and handle the request.

In this post, we will be using Zapier, a common automation software tool, to be our webhook handler. This will allow us to easily accept a webhook and use the response to let us know about the status, in this case via a Slack message.

First, we want to select the trigger in Zapier. For webhooks, we choose “Catch Hook” as the trigger, and also “Catch Hook” for the Trigger Event (Note this is a premium trigger, and is not free outside of the Zapier trial period).

This then directs us to the “Set up trigger” tab. This tab importantly contains the “Custom Webhook URL” that we will give Dolby.io. This URL is automatically generated and tied specifically to this automation, so keep it safe!

Linking the Dolby.io Webhook to the Destination

We can then use this webhook URL to set the callback URL in Dolby.io. This is done with a POST request to https://api.dolby.com/media/webhooks. Note that by setting this webhook value, all jobs associated with this API key will trigger a webhook. If you want webhooks to have different workflows, create a new application in your Dolby.io dashboard to generate a unique API key for every workflow desired.

Here is an example POST call to set the webhook url with cURL. For other languages, see our API Reference. Remember to set your API key either as the given environment variable, or by replacing $DOLBYIO_API_KEY with your API key.

curl --request POST 
     --url https://api.dolby.com/media/webhooks 
     --header 'Accept: application/json' 
     --header 'Authorization: Bearer <TOKEN>' 
     --header 'Content-Type: application/json' 
     --data '
{
     "callback": {
          "url": "<CUSTOM_URL>"
     }
}
'

The webhook URL should now be properly set for all API calls coming from this key. This is in direct contrast with callbacks, which need to be set for each individual API call. We suggest testing that it works properly using Zapier’s built in “Test trigger” section. We can do this by creating a new Media API call with the associated API key, and checking if Zapier properly received it after a couple of minutes.

If you find that you need to modify the webhook URL, or if you application already has one set, we can modify it by using a PUT call to https://api.dolby.com/media/webhooks instead. You will need to find the specific webhook_id that needs to be updated, which should be returned by the POST request we ran before, whether it failed or not.

curl --request PUT 
     --url 'https://api.dolby.com/media/webhooks?id=<WEBHOOK_ID>' 
     --header 'Accept: application/json' 
     --header 'Authorization: Bearer <TOKEN>' 
     --header 'Content-Type: application/json' 
     --data '
{
     "callback": {
          "url": "<CUSTOM_URL>"
     }
}
'

Using the Dolby.io Webhook Content

Now that we have the webhook properly set up in Zapier, we can modify the automation steps to determine what the workflow for a sent webhook will look like. In this example, we will send a Slack message to let you know the job has been completed. You will need to go through Zapier’s setup wizard to connect your Slack workspace with Zapier, which you can read more about here. This can be customized to a large variety of locations, including email, PagerDuty, or even another custom script.

As the webhook payload is sent in JSON, we can use this data in our response to help contextualize it. Zapier takes it one step further and includes each JSON attribute as a selectable parameter in the message text, which we use to populate our Slack response.

And now when we create a new job via the Media API, we get a Slack message telling us when it has completed!

Next steps

The number of applications of using Dolby.io webhooks are endless, so get creative! As mentioned earlier, webhooks work with workflows in AWS Lambda, Google Cloud Functions, and more, so it may make sense to fully automate the audio file upload to process to result workflow in your environment. This can also be a useful way to automatically record each processed file in a spreadsheet for data-keeping purposes, integrating the data into places such as Airtable, Smartsheet, or Google Docs.

For further reading, check out our Webhook and Callback documentation, or see how you can use webhooks in AWS, GCP, and Azure. And sign up for a free account on Dolby.io today!