# Using Callbacks to Return Transcripts to Your Server

When working with the Deepgram API, you can use a [callback](/guides/results-processing-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.

## Purpose

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](/guides/results-processing-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:

**`javascript`**

```javascript javascript
// 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`**

```bash cURL
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'
```

:::callout{intent="warning"}
Replace `YOUR_DEEPGRAM_API_KEY` with your [Deepgram API Key](/guides/guides-docs-create-additional-api-keys).
:::

### See Results

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

**`JSON`**

```json JSON
{ "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](/guides/self-hosted-deployments-2-reference-speech-to-text-listen-pre-recorded) or [Transcribe Streaming Audio: Responses](/guides/self-hosted-deployments-2-reference-speech-to-text-listen-streaming), and the [Feature documentation](/guides/streaming-audio-stt-streaming-feature-overview) for the features you enabled in your request.

## Related pages

- [Automatically Generating WebVTT & SRT Captions](./pre-recorded-audio-automatically-generating-webvtt-and-srt-captions.md)
- [Automatically Transcribe and Summarize Phone Calls](./pre-recorded-audio-automatically-transcribing-and-summarizing-phone-calls.md)
- [Getting Started with Deepgram Whisper Cloud](./pre-recorded-audio-deepgram-whisper-cloud.md)
- [Generating and Saving Transcripts From the Terminal](./pre-recorded-audio-generating-and-saving-transcripts-from-the-terminal.md)
- [When Callback Is Not Received](./pre-recorded-audio-payload-too-large.md)
- [When To Use Multichannel and Diarization](./pre-recorded-audio-multichannel-vs-diarization.md)
- [When To Use Keywords and Search](./pre-recorded-audio-keywords-vs-search.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.