By Vikram Vaswani - Developer Advocate

This tutorial was originally published at https://docs.rev.ai/resources/tutorials/get-started-api-webhooks/ on Mar 23, 2022.

Introduction

If you've used GitHub, PayPal, Slack or any number of other online services, you've already heard of (and maybe even used) webhooks. Webhooks provide an easy way for one application to notify another about a specific event - for example, a Git commit, a PayPal order or a Slack message - so that the notified application can take further action as needed.

Webhooks are a key component of building event-driven Web applications, and they're also well-supported in the various Rev AI ASR APIs. They provide a simple and efficient approach to programmatically managing job requests submitted through the Rev AI APIs.

Here's how it works:

1. An application submits a job to a Rev AI API for processing, supplying a webhook URL in the callback_url parameter.
2. Once job processing is complete, the API sends an HTTP POST message to the webhook URL containing the results of processing.
3. The webhook URL handler receives the HTTP POST request, parses the request body and implements further application-specific business logic as needed.

When developing event-driven ASR applications, it's important to be able to easily test and inspect the data structures received from the Rev AI APIs. A number of freely-available third-party tools and websites are available for webhook testing, including Webhook.site and RequestBin. This tutorial uses Webhook.site, but the procedure is broadly similar for other alternatives as well.

Assumptions

This tutorial assumes that:

• You have a Rev AI account and access token. If not, sign up for a free account and generate an access token.
• You have an audio file to transcribe. If not, use this example audio file from Rev AI.

Step 1: Obtain a webhook URL

The first step is to obtain a unique webhook URL, which you can do by visiting https://webhook.site/ and copying the URL shown on the page.

This webhook URL will remain active and waiting for requests for so long as you remain on the page.

Step 2: Add the webhook as callback_url in your API request

Submit an audio file for transcription to Rev AI using the command below. Replace the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI access token and the <WEBHOOK_URL> placeholder with the webhook URL obtained in Step 1. If you wish to use a different audio file, additionally replace the value of the media_url parameter with the URL to your audio file.

curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"media_url":"https://www.rev.ai/FTC_Sample_1.mp3","callback_url":"<WEBHOOK_URL>"}'

Your API call will return a response like this:

{
  "id":"8xBckmk6rAqu",
  "created_on":"2022-03-16T14:26:14.151Z",
  "name":"FTC_Sample_1.mp3",
  "callback_url":"https://webhook.site/84de11c2-e60b-4c15-928d-969cd26ce3cc",
  "media_url":"https://www.rev.ai/FTC_Sample_1.mp3",
  "status":"in_progress",
  "type":"async",
  "language":"en"
}

Step 3: Inspect the API response

For asynchronous transcription, the job's turnaround time is a function of the audio length. Files that are approximately 5 minutes in length will be returned within a few minutes. Longer files can take up to 15 minutes. Learn more about turnaround time.

Once the job's status changes, the Rev AI API will submit an HTTP POST request to the configured webhook URL. Here is an example of the POST message body:

{
  "job": {
    "id": "8xBckmk6rAqu",
    "created_on": "2022-03-16T14:26:14.151Z",
    "completed_on": "2022-03-16T14:26:53.601Z",
    "name": "FTC_Sample_1.mp3",
    "callback_url": "https://webhook.site/84de11c2-e60b-4c15-928d-969cd26ce3cc",
    "media_url": "https://www.rev.ai/FTC_Sample_1.mp3",
    "status": "transcribed",
    "duration_seconds": 107,
    "type": "async",
    "language": "en"
  }
}

This request to the webhook URL will be visible in the Webhook.site interface, which will auto-refresh to display the complete POST request details as shown below:

As the example above illustrates, the HTTP POST message includes the job identifier and detailed information on the job status, duration and completion time. This information can be used by the application for further decision-making or action, such as:

• Recording the job status in a database or message queue
• Invoking behavior (for example, an email or SMS notification) prompting additional user action
• Retrieving the transcript data
• Redirecting the message data to another system for further analysis and processing

Next steps

Webhooks provide a way to asynchronously receive notifications once a Rev AI job completes. Although optional, they are recommended in production environments, as they are significantly more efficient than repeatedly polling the API for job status and also relatively easy to understand and work with.

Learn more about Rev AI APIs and their support for webhooks by visiting the following links:

• Tutorial: Use Webhooks to Trigger Job Email Notifications with Node.js, Sendgrid and Express
• Documentation: Asynchronous Speech-To-Text API job submission and webhooks
• Documentation: Sentiment Analysis API job submission and webhooks
• Documentation: Topic Extraction API job submission and webhooks
• Documentation: Custom Vocabulary API submission and webhooks