Deepgram Webhooks Events
Table of Contents
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
callbackURL 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.