Processing Webhooks with RequestBin

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

Quite often when you submit a file to us, you don’t care how quickly it is available for searching as long as it’s processed. At other times, you want to know exactly when it’s available.

Clarify works on an asynchronous basis. This means that when you send us an audio or video file for processing, we don’t know when the file is going to be indexed and ready for searching. In practical terms, we immediately return the HTTP response code 201 Accepted to your current request and queue the file for retrieval and indexing.

And now the normal step is to wait and occasionally request your bundle information and check it’s state. That’s yet another chunk of code that needs to be written, debugged, and maintained. It’s annoying.

So let’s take a step back and rethink this. When we create the bundle, let’s use the notify_url parameter. We can set this to any publicly available URL we choose. Now when our bundle is ready, Clarify will automatically notify you.

Here’s an example using curl:

and an example using our PHP library:

And now we wait again but this time we don’t have to do anything else. We’ll automatically get two separate notifications at different stages in the system.

The first notification comes after Clarify has attempted to retrieve the file. We can immediately notify you if the file is missing (404), retrieved successfully (200), or if it wasn’t an audio/video file (415). In this sample notification, you can see the HTTP Response Code on line 36:

Now that we have the file, you can move it, perform your own processing, or whatever you need. There are other properties and information available but we’ll talk about those at a later time.

The second notification comes after we’ve performed our Automatic Speech Recognition (ASR) and Natural Language Processing (NLP) to build the search index. Here’s what that notification looks like:

Now that our processing is complete, you can use our API to search the file and retrieve the results.

You can build your own script to capture and process these results but for testing, you can make it even simpler using RequestBin. With RequestBin, you create a URL to capture this incoming callback and then plug that URL into the notify_url I noted above. Then when the webhook is called, you can view all of the data shown above without having to build anything yourself.

To be clear: In rare cases, you may receive either or both notifications multiple times.

If you have any questions, email us now.