Using Callbacks to Return Transcripts to Your Server

When working with the Deepgram API, you can use a callback to return your transcription to a URL on your server.

In this guide, you will learn how to use Deepgram's webhook to return a transcript generated by Deepgram's API to a callback URL that you provide.

What is a Webhook?

When using a web application, you often change the information being displayed on the web page you're on. For example, while browsing a list of blog posts, you may click on a link to show more posts. When you do this, the web application's UI on your machine (client) sends an HTTP request to the application's server. The server then sends a response back to your device, which then triggers a change in the UI of the web application.

But when a web application’s server wants to trigger an event based on something that’s happening on a remote server instead of a user action, we use webhooks.

A webhook is a 'reverse HTTP request' between servers rather than between a client and a server. A remote server (Deepgram) sends an HTTP POST request to a public URL on your application’s server every time an event occurs on their end, so you can trigger an event in your own application based on that update.

Waiting for a Transcript

When requesting a transcript from Deepgram, you can wait for it to be generated, but this can take a few more seconds than you might be able to wait for larger files. Instead, you can access Deepgram's webhook by including the callback feature in your request, which will allow you to redirect any transcription results to the URL of your choice.

Use Cases

Because you control the application that receives the webhook payload, you can build any additional business logic to run once you have data. You might:

• Send an email to your client to let them know that their transcript is complete with the results.
• Translate the transcript provided to your server to be displayed on your application’s UI.
• Send an SMS text to the user's phone with a brief preview of the results.

Prepare to Receive Incoming Transcripts on Your Server

To receive incoming transcripts on your server, you need to create an webhook consumer in your application. Your webhook consumer is basically a route handler, but instead of receiving requests from a user action, it is triggered by the service emitting webhooks--in this case Deepgram.

Since webhooks send a POST request to your application, your webhook consumer will need to create a POST route handler in your application. So the webhook consumer receiving transcripts on your server might look something like this:

// Require, initialize, and configure Express
const express = require("express");
const app = express();
app.use(express.json());

// This is the route handler our webhook will POST data to
app.post("/hook", (req, res) => {
	/*
        You could do anything here, such as:
        Add data to a database
        Trigger an email or SMS
        Automatically schedule an event on your application's UI
    */

	console.log(req.body); // See the data
	res.status(200).end(); // Return empty response to server
});

// Start express server
app.listen(3000);

For this example, assume that your application's URL is https://exampleco.com, which means your webhook consumer’s URL is https://exampleco.com/hook, based on how the route handler is configured in the sample code.

Send a Request to Deepgram

To send a request to Deepgram and receive the transcript on your server, you need to provide your webhook consumer's URL in the request to Deepgram. You do that by using Deepgram's Callback feature.

To transcribe audio from a file on your computer, for example, run the following cURL command in a terminal or your favorite API client:

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?callback=https://exampleco.com/hook'

🚧

Replace YOUR_DEEPGRAM_API_KEY with your Deepgram API Key.

See Results

When you supply a callback URL in your request to Deepgram's API, we will immediately respond with a request_id:

{ "request_id": "c22bea24-ecd3-4b53-bcbf-8ef087d905a5" }

We will then process your audio asynchronously and return the transcript to your server through the callback URL you provided.
If the HTTP status code of the response to the callback POST request is unsuccessful (not 200-299), Deepgram will retry the callback up to 10 times with a 30 second delay between attempts.

To learn more about the response returned to your server, see our API reference for Transcribe Pre-recorded Audio: Responses or Transcribe Streaming Audio: Responses, and the Feature documentation for the features you enabled in your request.