# 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. ```mermaid sequenceDiagram Client->>Rev AI: POST /jobs { notification_config {url: /my/url }} loop Rev AI->Rev AI: Process job end Rev AI-->>Client: POST /my/url { job: data } note left of Client: Process received data ``` 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](https://webhook.site/) and [RequestBin](https://requestbin.com/). This tutorial uses [Webhook.site](https://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](https://www.rev.ai/auth/signup) and [generate an access token](/get-started#step-1-get-your-access-token). - You have an audio file to transcribe. If not, use this [example audio file from Rev AI](https://www.rev.ai/FTC_Sample_1.mp3). ## 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/](https://webhook.site/) and copying the URL shown on the page. ![Webhook awaiting data](/assets/webhook-data-waiting.4dbf11c4f7329ec066e8424e53aac16a7d4a5161388d4221a0b4b146f4cf769c.edccfc87.png) 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 `` placeholder with your Rev AI access token and the `` 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. ```bash curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "source_config": {"url": "https://www.rev.ai/FTC_Sample_1.mp3"}, "notification_config": {"url": ""} }' ``` Your API call will return a response like this: ```bash { "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](/api/asynchronous#turnaround-time-and-chunking). 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: ```javascript { "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](/assets/webhook-data-received.95a81f58259014c2d4dc115d44228ea9373b278c4967949453670dcd35daa152.edccfc87.png) 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: - Documentation: Asynchronous Speech-To-Text API [job submission](/api/asynchronous) and [webhooks](/api/asynchronous/webhooks) - Documentation: Sentiment Analysis API [job submission](/api/sentiment-analysis) and [webhooks](/api/sentiment-analysis/webhooks) - Documentation: Topic Extraction API [job submission](/api/topic-extraction) and [webhooks](/api/topic-extraction/webhooks) - Documentation: Custom Vocabulary API [submission](/api/custom-vocabulary) and [webhooks](/api/custom-vocabulary/webhooks)