#Using Webhooks for Audio and Video Processing - by Keith @ Clarify / Caseysoftware

This was originally published on the Clarify blog on 17 September 2014.

Asynchronous processing is a key part of the Clarify API [Clarify API docs].

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:

<?php

require 'vendor/autoload.php';

$bundle = new \Clarify\Bundle('my api key');

$success = $bundle->create(
    'Dorothy and the Wizard of Oz',
    'http://media.clarify.io/audio/books/dorothyandthewizardinoz_01_baum_64kb.mp3',
    '',
    'http://example.org/my-callback-url.php'    // This is the webhook Clarify will call once the file is ready
);

create-bundle.php

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:

[example JSON payload, no longer available]

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:

[example JSON payload, no longer available]

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

Related Posts