Use Webhooks to Trigger Job Email Notifications with Node.js, SendGrid and Express

By Vikram Vaswani, Developer Advocate - Apr 05, 2022

Introduction

Webhooks are a common mechanism to asynchronously transfer information between multiple Web applications. The idea is simple: when a specific event occurs in an application, the application invokes a URL (the "webhook") in a downstream application and sends it a message containing relevant data. The downstream application uses the invocation of the webhook URL and the data passed to it to trigger a further process - this could be sending an email, updating a database record or even invoking another webhook.

Webhooks are a more efficient alternative to repeatedly pinging an application for event status, and they are well-supported in all the Rev AI APIs. This tutorial gets you started with Rev AI API webhooks, showing you how to implement a simple webhook that triggers an email notification when a user's transcription job completes.

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 a Twilio SendGrid account and API key. If not, sign up for a free account and generate a Twilio SendGrid API key . In order to send email through Twilio SendGrid, you must also verify your sender email address .
• You have a properly-configured Node.js development environment with Node.js v16.x or v17.x. If not, download and install Node.js for your operating system.
• You have some familiarity with the Express framework . If not, familiarize yourself with the basics using this example application .
• Your webhook will be available at a public URL. If not, or if you prefer to develop and test locally, download and install ngrok to generate a temporary public URL for your webhook.
• You have an audio file to transcribe. If not, use this example audio file from Rev AI .

Step 1: Install required packages

This tutorial will use:

• The Rev AI Node SDK , to submit transcription requests to the Rev AI Asynchronous Speech-to-Text API ;
• The Twilio SendGrid service , to send email notifications;
• The Express Web framework and body-parser middleware , to receive and parse webhook requests.

Begin by installing the required packages:

npm i revai-node-sdk @sendgrid/mail express body-parser

Step 2: Create the webhook handler

The webhook URL is specified as part of the job parameters submitted to the Rev AI API. On job completion, the Rev AI API will send an HTTP POST request containing JSON-encoded details of the completed job to the webhook URL. Here is an example of one such POST request:

{
  "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"
  }
}

The following example demonstrates how to implement a webhook handler that receives and parses the HTTP POST message from the Rev AI API and sends an email notification using Express and the Twilio SendGrid API client.

To use this example, you must first replace three placeholders:

• <SENDER_EMAIL_ADDRESS> and <RECIPIENT_EMAIL_ADDRESS> for the sender and recipient email addresses; and
• <SENDGRID_API_KEY> for the Twilio SendGrid API key.

const bodyParser = require('body-parser');
const express = require('express');
const sendgrid = require('@sendgrid/mail');

// Twilio SendGrid API key
const sendgridKey = '<SENDGRID_API_KEY>';
// sender email address
const senderEmail = '<SENDER_EMAIL>';
// recipient email address
const receiverEmail = '<RECEIVER_EMAIL>';

// set API key for SendGrid
sendgrid.setApiKey(sendgridKey);

// create Express application
const app = express();
app.use(bodyParser.json());

// handle requests to webhook endpoint
app.post('/hook', async req => {
  const job = req.body.job;
  console.log(`Received status for job id ${job.id}: ${job.status}`);    

  const message = {
    from: senderEmail,
    to: receiverEmail,
    subject: `Job ${job.id} is COMPLETE`,
    text: job.status === 'transcribed'
        ? `Log in at https://rev.ai/jobs/speech-to-text/ to collect your transcript.`
        : `An error occurred. Log in at https://rev.ai/jobs/speech-to-text/ to view details.`
  };

  try {
    await sendgrid.send(message);
    console.log('Email successfully sent');
  } catch (e) {
    console.error(e);
  }

});

//  start application on port 3000
app.listen(3000, () => {
  console.log('Webhook listening');
})

Save this code listing as index.js and take a closer look at it:

• This code listing begins by importing the required packages and credentials and creating a Twilio SendGrid API client.
• It starts an Express application on port 3000 and waits for incoming POST requests to the /hook URL route.
• When the application receives a POST request at /hook , it parses the incoming JSON message body and checks the job id and status .
• It prepares an email message with recipient, subject and - depending on the status - appropriate message body.
• It calls the sendgrid.send() method to deliver the message via the Twilio SendGrid API.
• Errors, if any, in mail delivery are sent to the console.

Step 3: Test the webhook

To see the webhook in action, first ensure that you have replaced the placeholders as described in the previous step and then start the application using the command below.

node index.js

Next, submit an audio file for transcription to Rev AI and include the notification_config parameter with the url option in your request. This parameter specifies the webhook URL that the Rev AI API should invoke on job completion.

Here is an example of submitting an audio file with a webhook using curl.

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": "<URL>"},"notification_config": {"url": "http://<WEBHOOK-HOST>/hook"}}'

If you prefer to submit the audio file using the Rev AI Node SDK, use this script instead (note this does not support authorization headers for the source or notification urls):

const { RevAiApiClient } = require('revai-node-sdk');

const revAiToken = '<REVAI_ACCESS_TOKEN>';
const webhookUrl = 'http://<WEBHOOK-HOST>/hook';
const fileUrl = '<URL>';

// define job options
const jobOptions = {
  notification_config: {
    url: webhookUrl
  }
};

// create Rev AI API client
const revAiClient = new RevAiApiClient(revAiToken);

// submit job
job = revAiClient.submitJobUrl(fileUrl, jobOptions);

In both cases, replace the <REVAI_ACCESS_TOKEN> placeholder with your Rev AI access token and the <URL> placeholder with the direct URL to your audio file. Additionally, replace the <WEBHOOK-HOST> placeholder as follows:

• If you are developing and testing in the public cloud, your Express application will typically be available at a public domain or IP address. In this case, replace the <WEBHOOK-HOST> placeholder with the correct domain name or IP address, including the port number 3000 if required.
• If you are developing and testing locally, your Express application will not be available publicly and you must therefore configure a public forwarding URL using a tool like ngrok . Obtain this URL using the command ngrok http 3000 and replace the <WEBHOOK-HOST> placeholder with the temporary forwarding URL generated by ngrok .

Once the job is processed, the Rev AI API will send a POST request to the webhook URL and shortly after, the recipient will receive an email notification.

Next steps

Learn more about using webhooks for asynchronous processing by visiting the following links:

• Documentation: Asynchronous Speech-To-Text API job submission and webhooks
• Documentation: Using ngrok
• Tutorial: Get Started with Rev AI API Webhooks