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

• Client sends transcription request with callback URL parameter

• Deepgram processes audio asynchronously

• Deepgram POSTs results to callback URL

• 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