Get Started with Rev AI API Webhooks

By Vikram Vaswani, Developer Advocate - 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 notification_config 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.
ClientRev AIPOST /jobs { notification_config {url: /my/url }}Process jobloopPOST /my/url { job: data }Process received dataClientRev AI

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:

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.

Webhook awaiting data

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 notification_config 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 source_config.url parameter with the URL to your audio file.

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

Your API call will return a response like this:

Copy
Copied
{
  "id":"8xBckmk6rAqu",
  "created_on":"2022-03-16T14:26:14.151Z",
  "name":"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:

Copy
Copied
{
  "job": {
    "id": "8xBckmk6rAqu",
    "created_on": "2022-03-16T14:26:14.151Z",
    "completed_on": "2022-03-16T14:26:53.601Z",
    "name": "FTC_Sample_1.mp3",
    "notification_config": {"url": "https://webhook.site/84de11c2-e60b-4c15-928d-969cd26ce3cc"},
    "source_config": {"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:

Webhook data

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: