deepgram-webhooks
starsforks
How to install deepgram-webhooks?
hookdeck/webhook-skills/deepgram-webhooks
$npx -y skills add hookdeck/webhook-skills --skill deepgram-webhooksReceive and verify Deepgram webhooks (callbacks). Use when setting up Deepgram webhook handlers, processing transcription callbacks, or handling asynchronous transcription results.
SKILL.md
| 1 | # Deepgram Webhooks |
| 2 | |
| 3 | ## When to Use This Skill |
| 4 | |
| 5 | - Setting up Deepgram callback handlers for transcription results |
| 6 | - Processing asynchronous transcription results from Deepgram |
| 7 | - Implementing webhook authentication for Deepgram callbacks |
| 8 | - Handling transcription completion events |
| 9 | |
| 10 | ## Essential Code |
| 11 | |
| 12 | Deepgram webhooks (callbacks) are used to receive transcription results asynchronously. When you provide a callback URL in your transcription request, Deepgram immediately responds with a `request_id` and sends the transcription results to your callback URL when processing is complete. |
| 13 | |
| 14 | ### Basic Webhook Handler |
| 15 | |
| 16 | ```javascript |
| 17 | // Express.js example |
| 18 | app.post('/webhooks/deepgram', express.raw({ type: 'application/json' }), (req, res) => { |
| 19 | // Verify webhook authenticity using dg-token header |
| 20 | const dgToken = req.headers['dg-token']; |
| 21 | |
| 22 | if (!dgToken) { |
| 23 | return res.status(401).send('Missing dg-token header'); |
| 24 | } |
| 25 | |
| 26 | // Verify the token matches your expected API Key Identifier |
| 27 | // The dg-token contains the API Key Identifier used in the original request |
| 28 | if (dgToken !== process.env.DEEPGRAM_API_KEY_ID) { |
| 29 | return res.status(403).send('Invalid dg-token'); |
| 30 | } |
| 31 | |
| 32 | // Parse the transcription result |
| 33 | const transcriptionResult = JSON.parse(req.body.toString()); |
| 34 | |
| 35 | // Process the transcription |
| 36 | console.log('Received transcription:', transcriptionResult); |
| 37 | |
| 38 | // Return success to prevent retries |
| 39 | res.status(200).send('OK'); |
| 40 | }); |
| 41 | ``` |
| 42 | |
| 43 | ### Authentication Methods |
| 44 | |
| 45 | Deepgram supports two authentication methods for webhooks: |
| 46 | |
| 47 | 1. **dg-token Header**: Automatically included, contains the API Key Identifier |
| 48 | 2. **Basic Auth**: Embed credentials in the callback URL |
| 49 | |
| 50 | ```javascript |
| 51 | // Using dg-token header (recommended) |
| 52 | const verifyDgToken = (req, res, next) => { |
| 53 | const dgToken = req.headers['dg-token']; |
| 54 | |
| 55 | if (!dgToken || dgToken !== process.env.DEEPGRAM_API_KEY_ID) { |
| 56 | return res.status(403).send('Invalid authentication'); |
| 57 | } |
| 58 | |
| 59 | next(); |
| 60 | }; |
| 61 | |
| 62 | // Basic Auth in callback URL |
| 63 | // https://username:password@your-domain.com/webhooks/deepgram |
| 64 | ``` |
| 65 | |
| 66 | ### Making a Request with Callback |
| 67 | |
| 68 | ```bash |
| 69 | curl \ |
| 70 | --request POST \ |
| 71 | --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \ |
| 72 | --header 'Content-Type: audio/wav' \ |
| 73 | --data-binary @audio.wav \ |
| 74 | --url 'https://api.deepgram.com/v1/listen?callback=https://your-domain.com/webhooks/deepgram' |
| 75 | ``` |
| 76 | |
| 77 | ## Common Event Types |
| 78 | |
| 79 | Deepgram sends transcription results as webhook payloads. The structure varies based on the features enabled in your request: |
| 80 | |
| 81 | | Field | Description | Always Present | |
| 82 | |-------|-------------|----------------| |
| 83 | | `request_id` | Unique identifier for the transcription request | Yes | |
| 84 | | `created` | Timestamp when transcription was created | Yes | |
| 85 | | `duration` | Length of the audio in seconds | Yes | |
| 86 | | `channels` | Number of audio channels | Yes | |
| 87 | | `results` | Transcription results by channel | Yes | |
| 88 | | `results.channels[].alternatives` | Transcription alternatives | Yes | |
| 89 | | `results.channels[].alternatives[].transcript` | The transcribed text | Yes | |
| 90 | | `results.channels[].alternatives[].confidence` | Confidence score (0-1) | Yes | |
| 91 | |
| 92 | ## Environment Variables |
| 93 | |
| 94 | ```bash |
| 95 | # Your Deepgram API Key (for making requests) |
| 96 | DEEPGRAM_API_KEY=your_api_key_here |
| 97 | |
| 98 | # API Key Identifier (shown in Deepgram console, used to verify dg-token) |
| 99 | # Note: This is NOT your API Key secret - it's a unique identifier shown |
| 100 | # in the Deepgram console that identifies which API key was used for a request |
| 101 | DEEPGRAM_API_KEY_ID=your_api_key_id_here |
| 102 | |
| 103 | # Your webhook endpoint URL |
| 104 | WEBHOOK_URL=https://your-domain.com/webhooks/deepgram |
| 105 | ``` |
| 106 | |
| 107 | ## Local Development |
| 108 | |
| 109 | For local webhook testing, install Hookdeck CLI: |
| 110 | |
| 111 | ```bash |
| 112 | # Create a local tunnel (no account required) |
| 113 | npx hookdeck-cli listen 3000 deepgram --path /webhooks/deepgram |
| 114 | |
| 115 | # Use the provided URL as your callback URL when making Deepgram requests |
| 116 | ``` |
| 117 | |
| 118 | This provides: |
| 119 | - Local tunnel URL for testing |
| 120 | - Web UI for inspecting webhook payloads |
| 121 | - Request history and debugging tools |
| 122 | |
| 123 | ## Important Notes |
| 124 | |
| 125 | ### Retry Behavior |
| 126 | - Deepgram retries failed callbacks (non-200-299 status) up to 10 times |
| 127 | - 30-second delay between retry attempts |
| 128 | - Always return 200-299 status for successfully processed webhooks |
| 129 | |
| 130 | ### Port Restrictions |
| 131 | - Only ports 80, 443, 8080, and 8443 are allowed for callbacks |
| 132 | - Ensure your webhook endpoint uses one of these ports |
| 133 | |
| 134 | ### No Signature Verification |
| 135 | - Deepgram uses a simple token-based authentication via the dg-token header rather than cryptographic HMAC signatures used by other providers |
| 136 | - Authentication relies on the `dg-token` header or Basic Auth |
| 137 | - Always use HTTPS for webhook endpoints |
| 138 | |
| 139 | ## Resources |
| 140 | |
| 141 | - [overview.md] |
People who liked this also viewed
6 picksType
- paperclip-create-agentCreate new agents in Paperclip with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hSkillsJul 2026
- subagent-driven-developmentUse when executing implementation plans with independent tasks in the current sessionSkillsJul 2026
- dispatching-parallel-agentsUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesSkillsJul 2026
- browser-act-skill-forgeForges reusable Skill packages (SKILL.md + scripts) from website exploration via browser-act — no re-exploration later. Use when: user wants a reusable Skill for any website, needs to understand a sitSkillsJul 2026
- wizardGenerate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, confirming each stSkillsJul 2026
- wonda-cliUsing the Wonda CLI to generate images, videos, music, and audio from the terminal — plus LinkedIn, Reddit, and X/Twitter research and automationSkillsJul 2026
