Deepgram Webhooks & Callbacks

Prerequisites

A verified callback endpoint, signature/authentication requirements, idempotency store, and redacted observability.
A data-retention/consent decision and an owner for failed callback recovery.

Examples

Validate the callback signature before parsing its body, deduplicate by an opaque event ID, acknowledge promptly, and write only state/result metadata to logs. Test with a development event; retry transient failures with bounded backoff and quarantine terminal failures rather than replaying audio/transcripts blindly.

Overview

Implement async transcription with Deepgram's callback feature. When you pass a callback URL, Deepgram returns a request_id immediately, processes audio in the background, and POSTs results to your endpoint. Supports HTTP and WebSocket callbacks with automatic retry (10 attempts, 30s intervals).

Deepgram Callback Flow

1. Client -> POST /v1/listen?callback=https://you.com/webhook  (with audio)
2. Deepgram -> 200 { request_id: "..." }                       (immediate)
3. Deepgram processes audio asynchronously
4. Deepgram -> POST https://you.com/webhook                    (results)
   Retries up to 10 times (30s delay) on non-2xx response

Instructions

Step 1: Submit Async Transcription

import { createClient } from '@deepgram/sdk';

const deepgram = createClient(process.env.DEEPGRAM_API_KEY!);

async function submitAsync(audioUrl: string, callbackUrl: string) {
  // Deepgram sends transcription via callback URL instead of
  // holding the connection open.
  const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
    { url: audioUrl },
    {
      model: 'nova-3',
      smart_format: true,
      diarize: true,
      utterances: true,
      callback: callbackUrl,  // Your HTTPS endpoint
      // callback_method: 'put',  // Optional: use PUT instead of POST
    }
  );

  if (error) throw new Error(`Submit failed: ${error.message}`);

  // Deepgram returns immediately with request_id
  const requestId = result.metadata.request_id;
  console.log(`Submitted. Request ID: ${requestId}`);
  console.log(`Results will be POSTed to: ${callbackUrl}`);
  return requestId;
}

// Also works with direct curl:
// curl -X POST 'https://api.deepgram.com/v1/listen?model=nova-3&callback=https://you.com/webhook' \
//   -H "Authorization: Token $DEEPGRAM_API_KEY" \
//   -H "Content-Type: application/json" \
//   -d '{"url":"https://example.com/audio.wav"}'

Step 2: Callback Server

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Use raw body for HMAC signature verification
app.use('/webhooks/deepgram', express.raw({ type: 'application/json', limit: '50mb' }));

app.post('/webhooks/deepgram', async (req, res) => {
  try {
    // 1. Verify signature (if webhook secret configured)
    const signature = req.headers['x-deepgram-signature'] as string;
    if (process.env.DEEPGRAM_WEBHOOK_SECRET && signature) {
      const expected = crypto
        .createHmac('sha256', process.env.DEEPGRAM_WEBHOOK_SECRET)
        .update(req.body)
        .digest('hex');

      // Timing-safe comparison to prevent timing attacks
      if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
        console.error('Invalid webhook signature');
        return res.status(401).json({ error: 'Invalid signature' });
      }
    }

    // 2. Parse result
    const result = JSON.parse(req.body.toString());
    const requestId = result.metadata?.request_id;
    const transcript = result.results?.channels?.[0]?.alternatives?.[0]?.transcript;
    const duration = result.metadata?.duration;

    console.log(`Callback received: ${requestId}`);
    console.log(`Duration: ${duration}s`);
    console.log(`Transcript: ${transcript?.substring(0, 200)}...`);

    // 3. Process and store
    await processTranscriptionResult(requestId, result);

    // 4. Return 200 — Deepgram retries on non-2xx
    res.status(200).json({ received: true, request_id: requestId });
  } catch (err: any) {
    console.error('Callback processing error:', err.message);
    // Return 500 to trigger Deepgram retry
    res.status(500).json({ error: 'Processing failed' });
  }
});

async function processTranscriptionResult(requestId: string, result: any) {
  const transcript = result.results.channels[0].alternatives[0];

  // Store transcript
  const record = {
    requestId,
    transcript: transcript.transcript,
    confidence: transcript.confidence,
    duration: result.metadata.duration,
    words: transcript.words?.length ?? 0,
    utterances: result.results.utterances?.map((u: any) => ({
      speaker: u.speaker,
      text: u.transcript,
      start: u.start,
      end: u.end,
    })),
    processedAt: new Date().toISOString(),
  };

  // Save to database / notify clients / trigger downstream
  console.log('Processed:', JSON.stringify(record, null, 2));
  return record;
}

Step 3: Job Tracking with Redis

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL ?? 'redis://localhost:6379');

class TranscriptionJobTracker {
  async submit(requestId: string, metadata: Record<string, any>) {
    await redis.hset(`job:${requestId}`, {
      status: 'processing',
      submittedAt: new Date().toISOString(),
      ...metadata,
    });
    // Auto-expire after 24 hours
    await redis.expire(`job:${requestId}`, 86400);
  }

  async complete(requestId: string, result: any) {
    await redis.hset(`job:${requestId}`, {
      status: 'completed',
      completedAt: new Date().toISOString(),
      transcript: result.results.channels[0].alternatives[0].transcript,
      duration: result.metadata.duration,
    });
    // Publish for real-time notification
    await redis.publish('transcription:complete', JSON.stringify({
      requestId,
      duration: result.metadata.duration,
    }));
  }

  async getStatus(requestId: string) {
    return redis.hgetall(`job:${requestId}`);
  }
}

// Client-facing status endpoint
app.get('/api/transcription/:requestId', async (req, res) => {
  const tracker = new TranscriptionJobTracker();
  const status = await tracker.getStatus(req.params.requestId);

  if (!status || Object.keys(status).length === 0) {
    return res.status(404).json({ error: 'Job not found' });
  }
  res.json(status);
});

Step 4: Client SDK with Submit/Poll/Wait

class AsyncTranscriptionClient {
  private deepgram: ReturnType<typeof createClient>;
  private baseUrl: string;

  constructor(apiKey: string, serverBaseUrl: string) {
    this.deepgram = createClient(apiKey);
    this.baseUrl = serverBaseUrl;
  }

  async submit(audioUrl: string): Promise<string> {
    const callbackUrl = `${this.baseUrl}/webhooks/deepgram`;
    const { result, error } = await this.deepgram.listen.prerecorded.transcribeUrl(
      { url: audioUrl },
      { model: 'nova-3', smart_format: true, diarize: true, callback: callbackUrl }
    );
    if (error) throw error;
    return result.metadata.request_id;
  }

  async poll(requestId: string): Promise<any> {
    const res = await fetch(`${this.baseUrl}/api/transcription/${requestId}`);
    if (res.status === 404) return null;
    return res.json();
  }

  async waitForResult(requestId: string, timeoutMs = 300000): Promise<any> {
    const start = Date.now();
    while (Date.now() - start < timeoutMs) {
      const status = await this.poll(requestId);
      if (status?.status === 'completed') return status;
      if (status?.status === 'failed') throw new Error('Transcription failed');
      await new Promise(r => setTimeout(r, 2000));  // Poll every 2s
    }
    throw new Error('Timeout waiting for transcription');
  }
}

// Usage:
const client = new AsyncTranscriptionClient(
  process.env.DEEPGRAM_API_KEY!,
  'https://your-server.com'
);
const requestId = await client.submit('https://example.com/long-recording.wav');
const result = await client.waitForResult(requestId);

Step 5: Local Testing with ngrok

# Expose local callback server to Deepgram
ngrok http 3000

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

Step 6: Idempotent Processing

// Deepgram retries callbacks — ensure idempotent processing
const processedRequests = new Set<string>();

app.post('/webhooks/deepgram', async (req, res) => {
  const result = JSON.parse(req.body.toString());
  const requestId = result.metadata?.request_id;

  // Skip if already processed
  if (processedRequests.has(requestId)) {
    console.log(`Duplicate callback for ${requestId} — skipping`);
    return res.status(200).json({ received: true, duplicate: true });
  }

  processedRequests.add(requestId);
  // In production, use Redis SET with NX for distributed dedup:
  // const isNew = await redis.set(`processed:${requestId}`, '1', 'NX', 'EX', 86400);
  // if (!isNew) return res.status(200).json({ duplicate: true });

  await processTranscriptionResult(requestId, result);
  res.status(200).json({ received: true });
});

Output

Async transcription submission with callback URL
Callback server with signature verification
Redis-backed job tracking with pub/sub notifications
Client SDK with submit/poll/wait pattern
Idempotent callback processing
Local testing setup with ngrok

Error Handling

Issue	Cause	Solution
Callback not received	Endpoint unreachable	Check HTTPS, firewall, use ngrok for local
Duplicate callbacks	Deepgram retry after slow response	Implement idempotency with request_id
Invalid signature	Wrong webhook secret	Verify `DEEPGRAM_WEBHOOK_SECRET` matches Console
Processing timeout	Slow downstream	Return 200 immediately, process async
Large payload	Long audio transcript	Increase `express.raw` limit

deepgram-webhooks-events