deepgram-webhooks-events

Deepgram Webhooks Events

Table of Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Implement callback URL handling for asynchronous Deepgram transcription workflows. Covers callback server setup, signature verification, result processing, retry mechanisms, and client SDK for async operations.

Prerequisites

• Publicly accessible HTTPS endpoint
• Deepgram API key with transcription permissions
• Request validation capabilities
• Secure storage for transcription results

Deepgram Callback Flow

1. Client sends transcription request with callback URL parameter
2. Deepgram processes audio asynchronously
3. Deepgram POSTs results to callback URL
4. Your server processes, stores results, and notifies clients

Instructions

Step 1: Create Callback Endpoint

Set up an Express endpoint at /webhooks/deepgram using raw body parsing for signature verification.

Step 2: Implement Signature Verification

Verify callbacks using HMAC-SHA256 with timing-safe comparison against x-deepgram-signature header.

Step 3: Process Results

Extract transcript, confidence, words, and metadata from the callback payload. Store in database and Redis.

Step 4: Notify Clients

Push results via WebSocket to connected clients and/or send email notifications.

Step 5: Add Retry Handling

Implement CallbackRetryHandler with exponential backoff (max 3 retries, 5s-60s delay).

Output

• Callback server with signature verification
• Async transcription service with job tracking (Redis)
• Store and notify services
• Retry mechanism for failed processing
• Client SDK with submit/poll/wait pattern

Error Handling

Issue	Cause	Resolution
Invalid signature	Wrong webhook secret	Verify DEEPGRAM_WEBHOOK_SECRET matches
Callback not received	Endpoint not reachable	Check HTTPS, firewall rules, use ngrok for local
Processing timeout	Slow downstream services	Increase timeout, add async processing queue
Duplicate callbacks	Network retry	Implement idempotency using request_id

Examples

Test Callback Locally

set -euo pipefail
# Expose local server
ngrok http 3000  # 3000: 3 seconds in ms

# Submit async transcription
curl -X POST 'https://api.deepgram.com/v1/listen?callback=https://your-ngrok.ngrok.io/webhooks/deepgram&model=nova-2' \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://static.deepgram.com/examples/nasa-podcast.wav"}'

See detailed implementation for advanced patterns.

Resources

• Deepgram Callback Documentation
• Webhook Best Practices
• ngrok Documentation