# STT Callback

`callback` _string_

Pre-recorded  Streaming\:Nova  All available languages

Deepgram’s Callback feature allows you to supply a callback URL to which transcriptions can be returned. When passed, Deepgram will immediately respond with a `request_id` before processing your audio asynchronously.

## Enable Feature

To enable Callback, when you call Deepgram’s API, add a `callback` parameter in the query string and set it to the URL to which you would like transcriptions sent:

`callback=URL`

To transcribe audio from a file on your computer, 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=URL'
```

## URL Structure

An example URL is `https://example.com/callback`.

Your callback URLs may reference the following protocols:

- For pre-recorded audio: `http` or `https`
- For streaming audio, `http`, `https`, `ws`, or `wss:`

## Authenticating Callback Requests

Authentication ensures the security and integrity of callback requests. There are two main methods for authenticating callback requests: using Basic Auth and utilizing the dg-token request header.

### Using Basic Auth

You may embed username-password authentication credentials in the callback URL in the format `https://username:[email protected]`. However, it's important to note that only ports 80, 443, 8080, and 8443 are permitted for callbacks.

:::callout{intent="warning"}
Only ports 80, 443, 8080, and 8443 are permitted for callbacks.
:::

### Using the `dg-token` Request Header

Alternatively, the callback request may include a header named `dg-token`. When present, this header is set to the API Key Identifier associated with the API Key used to submit the original request, which lets you verify that the callback came from Deepgram.

:::callout{intent="note"}
The `dg-token` header is not guaranteed on every callback request, so this method is less reliable than Basic Auth or [Extra Metadata](/guides/results-processing-extra-metadata). Use `dg-token` as a supplementary check rather than your only means of authentication.
:::

## Results

Depending on the type of submitted audio, the response will vary.

### Pre-recorded Audio

When Deepgram has finished analyzing the audio, it will send a `POST` request to the provided callback URL with an appropriate HTTP status code.

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.

## Using `CallBack_Method`

To enable the Callback Method, include the `callback_method` parameter in the query string. By default, the method supports `POST`, but you can specify `PUT` instead.

**`cURL`**

```bash cURL
curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: text/plain' \
  --data 'Your Text.' \
  --url 'https://api.deepgram.com/v1/listen?callback=URL&callback_method=put'
```

### Streaming Audio

As Deepgram analyzes the audio, the way in which it sends requests back to the provided callback URL varies:

- If your callback URL begins with `http://` or `https://`, then Deepgram will send `POST` requests to the callback server for each streaming response.
- If your callback URL begins with `ws://` or `wss://`, then Deepgram will establish a WebSocket connection with the callback server and send WebSocket text messages that contain the streaming responses.

:::callout{intent="warning"}
If a WebSocket callback connection is disconnected at any point, the entire real-time transcription stream is killed; this maintains the strong guarantee of a one-to-one relationship between incoming real-time connections and outgoing WebSocket callback connections.
:::

***

## Related pages

- [Amazon SageMaker](./amazon-sagemaker-index.md)
- [Aura](./aura-index.md)
- [Changelog](../changelog.md)
- [Custom Vocabulary](./custom-vocabulary-index.md)
- [Deepgram's Docs](../index.md)
- [Deployment](./deployment-index.md)
- [Docker/Podman](./docker-podman-index.md)
- [Features](./features-index.md)
- [Flux TTS](./flux-tts-index.md)
- [Formatting](./formatting-index.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.