deepgram-webhooks-events

name	deepgram-webhooks-events
description	Implement Deepgram callback and webhook handling for async transcription. Use when implementing callback URLs, processing async transcription results, or handling Deepgram event notifications. Trigger: "deepgram callback", "deepgram webhook", "async transcription", "deepgram events", "deepgram notifications", "deepgram async".
allowed-tools	Read, Write, Edit, Bash(curl:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
compatible-with	claude-code, codex, openclaw
tags	["saas","deepgram","webhooks","transcription","async"]

Deepgram Webhooks & Callbacks

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
    }
  );

   (error)   ();

  
   requestId = result..;
  .();
  .();
   requestId;
}