Using Webhooks for Audio and Video Processing

Originally published on the Clarify.io blog. View archived copy.

Asynchronous processing is a key part of the Clarify API.

When you create a new media bundle, we have to retrieve the media file, apply our algorithms, process it through our internal APIs, and retrieve the time-series search index. All of that takes time. While your application could poll our systems to figure out if a file is ready, that’s not efficient. In fact, forcing you to handle that polling and back off adds complex logic to your application.

Instead, we use callbacks or webhooks.

In concept, webhooks are quite simple. When you create a bundle with us, you specify a notify_url. When that bundle is done processing, we perform an HTTP POST to your url. The code in question looks something like this:

Once our algorithms are complete, we’ll perform two types of HTTP POSTs to your URL: a bundle notification and track notifications. This notification will be a JSON payload containing fields such as bundle_id, external_id (if specified), bundle_processing_cost, and a link to the detailed track information. Here’s an example payload:

Track notifications are a bit different. Since a bundle can have multiple tracks – such as a stereo audio file – each track will receive its own notification after it is fetched and verified. If there was any issue – like an incorrect URL – you can catch that notification and take action. That notification will include most of the same parameters as the bundle notification in addition to the track specific information. Here’s an example payload:

It’s vital to remember that this payload is simply JSON and not a set of HTTP POST parameters. Therefore, you should be able to capture the payload and just parse the JSON in your favorite programming language.

If you run into any challenges or problems, don’t hesitate to drop us a note at support@clarify.io