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:

attention

The SendGrid API key should be configured with the Full Access privilege. This setting can configured at the time of creating the API key.

Step 1: Install required packages

This tutorial will use:

Begin by installing the required packages:

Copy
Copied
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:

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

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.
Copy
Copied
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.

Copy
Copied
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.

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": "<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 authentication headers for the source or notification urls):

Copy
Copied
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.

attention

If a webhook doesn't work as expected, you can test and inspect the webhook response.

Next steps

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