# Deepgram Webhooks

## When to Use This Skill

* Setting up Deepgram callback handlers for transcription results
* Processing asynchronous transcription results from Deepgram
* Implementing webhook authentication for Deepgram callbacks
* Handling transcription completion events

## Essential Code

Deepgram webhooks (callbacks) are used to receive transcription results asynchronously. When you provide a callback URL in your transcription request, Deepgram immediately responds with a `request_id` and sends the transcription results to your callback URL when processing is complete.

### Basic Webhook Handler

```javascript
// Express.js example
app.post('/webhooks/deepgram', express.raw({ type: 'application/json' }), (req, res) => {
  // Verify webhook authenticity using dg-token header
  const dgToken = req.headers['dg-token'];

  if (!dgToken) {
    return res.status(401).send('Missing dg-token header');
  }

  // Verify the token matches your expected API Key Identifier
  // The dg-token contains the API Key Identifier used in the original request
  if (dgToken !== process.env.DEEPGRAM_API_KEY_ID) {
    return res.status(403).send('Invalid dg-token');
  }

  // Parse the transcription result
  const transcriptionResult = JSON.parse(req.body.toString());

  // Process the transcription
  console.log('Received transcription:', transcriptionResult);

  // Return success to prevent retries
  res.status(200).send('OK');
});

```

### Authentication Methods

Deepgram supports two authentication methods for webhooks:

1. dg-token Header: Automatically included, contains the API Key Identifier
2. Basic Auth: Embed credentials in the callback URL

```javascript
// Using dg-token header (recommended)
const verifyDgToken = (req, res, next) => {
  const dgToken = req.headers['dg-token'];

  if (!dgToken || dgToken !== process.env.DEEPGRAM_API_KEY_ID) {
    return res.status(403).send('Invalid authentication');
  }

  next();
};

// Basic Auth in callback URL
// https://username:password@your-domain.com/webhooks/deepgram

```

### Making a Request with Callback

```bash
curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @audio.wav \
  --url 'https://api.deepgram.com/v1/listen?callback=https://your-domain.com/webhooks/deepgram'

```

## Common Event Types

Deepgram sends transcription results as webhook payloads. The structure varies based on the features enabled in your request:

| Field | Description | Always Present |
| --- | --- | --- |
| `request_id` | Unique identifier for the transcription request | Yes |
| `created` | Timestamp when transcription was created | Yes |
| `duration` | Length of the audio in seconds | Yes |
| `channels` | Number of audio channels | Yes |
| `results` | Transcription results by channel | Yes |
| `results.channels[].alternatives` | Transcription alternatives | Yes |
| `results.channels[].alternatives[].transcript` | The transcribed text | Yes |
| `results.channels[].alternatives[].confidence` | Confidence score (0-1) | Yes |

## Environment Variables

```bash
# Your Deepgram API Key (for making requests)
DEEPGRAM_API_KEY=your_api_key_here

# API Key Identifier (shown in Deepgram console, used to verify dg-token)
# Note: This is NOT your API Key secret - it's a unique identifier shown
# in the Deepgram console that identifies which API key was used for a request
DEEPGRAM_API_KEY_ID=your_api_key_id_here

# Your webhook endpoint URL
WEBHOOK_URL=https://your-domain.com/webhooks/deepgram

```

## Local Development

For local webhook testing, install Hookdeck CLI:

```bash
# Create a local tunnel (no account required)
npx hookdeck-cli listen 3000 deepgram --path /webhooks/deepgram

# Use the provided URL as your callback URL when making Deepgram requests

```

This provides:

* Local tunnel URL for testing
* Web UI for inspecting webhook payloads
* Request history and debugging tools

## Important Notes

### Retry Behavior

* Deepgram retries failed callbacks (non-200-299 status) up to 10 times
* 30-second delay between retry attempts
* Always return 200-299 status for successfully processed webhooks

### Port Restrictions

* Only ports 80, 443, 8080, and 8443 are allowed for callbacks
* Ensure your webhook endpoint uses one of these ports

### No Signature Verification

* Deepgram uses a simple token-based authentication via the dg-token header rather than cryptographic HMAC signatures used by other providers
* Authentication relies on the `dg-token` header or Basic Auth
* Always use HTTPS for webhook endpoints

## Resources

* [overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/deepgram-webhooks/references/overview.md) - What Deepgram webhooks are, transcription events
* [setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/deepgram-webhooks/references/setup.md) - Configure callbacks in Deepgram API requests
* [verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/deepgram-webhooks/references/verification.md) - Authentication methods and security considerations
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/deepgram-webhooks/examples/) - Complete implementations for Express, Next.js, and FastAPI