{"id":"ee399ee8-a4af-4f1c-b737-b892f6f155e9","shortId":"H48pGw","kind":"skill","title":"deepgram-webhooks","tagline":"Receive and verify Deepgram webhooks (callbacks). Use when setting up Deepgram webhook handlers, processing transcription callbacks, or handling asynchronous transcription results.","description":"# Deepgram Webhooks\n\n## When to Use This Skill\n\n- Setting up Deepgram callback handlers for transcription results\n- Processing asynchronous transcription results from Deepgram\n- Implementing webhook authentication for Deepgram callbacks\n- Handling transcription completion events\n\n## Essential Code\n\nDeepgram 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.\n\n### Basic Webhook Handler\n\n```javascript\n// Express.js example\napp.post('/webhooks/deepgram', express.raw({ type: 'application/json' }), (req, res) => {\n  // Verify webhook authenticity using dg-token header\n  const dgToken = req.headers['dg-token'];\n\n  if (!dgToken) {\n    return res.status(401).send('Missing dg-token header');\n  }\n\n  // Verify the token matches your expected API Key Identifier\n  // The dg-token contains the API Key Identifier used in the original request\n  if (dgToken !== process.env.DEEPGRAM_API_KEY_ID) {\n    return res.status(403).send('Invalid dg-token');\n  }\n\n  // Parse the transcription result\n  const transcriptionResult = JSON.parse(req.body.toString());\n\n  // Process the transcription\n  console.log('Received transcription:', transcriptionResult);\n\n  // Return success to prevent retries\n  res.status(200).send('OK');\n});\n```\n\n### Authentication Methods\n\nDeepgram supports two authentication methods for webhooks:\n\n1. **dg-token Header**: Automatically included, contains the API Key Identifier\n2. **Basic Auth**: Embed credentials in the callback URL\n\n```javascript\n// Using dg-token header (recommended)\nconst verifyDgToken = (req, res, next) => {\n  const dgToken = req.headers['dg-token'];\n\n  if (!dgToken || dgToken !== process.env.DEEPGRAM_API_KEY_ID) {\n    return res.status(403).send('Invalid authentication');\n  }\n\n  next();\n};\n\n// Basic Auth in callback URL\n// https://username:password@your-domain.com/webhooks/deepgram\n```\n\n### Making a Request with Callback\n\n```bash\ncurl \\\n  --request POST \\\n  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \\\n  --header 'Content-Type: audio/wav' \\\n  --data-binary @audio.wav \\\n  --url 'https://api.deepgram.com/v1/listen?callback=https://your-domain.com/webhooks/deepgram'\n```\n\n## Common Event Types\n\nDeepgram sends transcription results as webhook payloads. The structure varies based on the features enabled in your request:\n\n| Field | Description | Always Present |\n|-------|-------------|----------------|\n| `request_id` | Unique identifier for the transcription request | Yes |\n| `created` | Timestamp when transcription was created | Yes |\n| `duration` | Length of the audio in seconds | Yes |\n| `channels` | Number of audio channels | Yes |\n| `results` | Transcription results by channel | Yes |\n| `results.channels[].alternatives` | Transcription alternatives | Yes |\n| `results.channels[].alternatives[].transcript` | The transcribed text | Yes |\n| `results.channels[].alternatives[].confidence` | Confidence score (0-1) | Yes |\n\n## Environment Variables\n\n```bash\n# Your Deepgram API Key (for making requests)\nDEEPGRAM_API_KEY=your_api_key_here\n\n# API Key Identifier (shown in Deepgram console, used to verify dg-token)\n# Note: This is NOT your API Key secret - it's a unique identifier shown\n# in the Deepgram console that identifies which API key was used for a request\nDEEPGRAM_API_KEY_ID=your_api_key_id_here\n\n# Your webhook endpoint URL\nWEBHOOK_URL=https://your-domain.com/webhooks/deepgram\n```\n\n## Local Development\n\nFor local webhook testing, install Hookdeck CLI:\n\n```bash\n# Create a local tunnel (no account required)\nnpx hookdeck-cli listen 3000 deepgram --path /webhooks/deepgram\n\n# Use the provided URL as your callback URL when making Deepgram requests\n```\n\nThis provides:\n- Local tunnel URL for testing\n- Web UI for inspecting webhook payloads\n- Request history and debugging tools\n\n## Important Notes\n\n### Retry Behavior\n- Deepgram retries failed callbacks (non-200-299 status) up to 10 times\n- 30-second delay between retry attempts\n- Always return 200-299 status for successfully processed webhooks\n\n### Port Restrictions\n- Only ports 80, 443, 8080, and 8443 are allowed for callbacks\n- Ensure your webhook endpoint uses one of these ports\n\n### No Signature Verification\n- Deepgram uses a simple token-based authentication via the dg-token header rather than cryptographic HMAC signatures used by other providers\n- Authentication relies on the `dg-token` header or Basic Auth\n- Always use HTTPS for webhook endpoints\n\n## Resources\n\n- [overview.md](references/overview.md) - What Deepgram webhooks are, transcription events\n- [setup.md](references/setup.md) - Configure callbacks in Deepgram API requests\n- [verification.md](references/verification.md) - Authentication methods and security considerations\n- [examples/](examples/) - Complete implementations for Express, Next.js, and FastAPI\n\n## Recommended: webhook-handler-patterns\n\nFor production handlers, install the patterns skill alongside this one. Key references (links work when only this skill is installed):\n\n- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)\n- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)\n- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)\n\n## Related Skills\n\n- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe payment webhooks\n- [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify store webhooks\n- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository webhooks\n- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic\n- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers","tags":["deepgram","webhooks","webhook","skills","hookdeck","agent-skills","ai-coding","api-integrations","event-driven","github-webhooks","llm-tools","shopify-webhooks"],"capabilities":["skill","source-hookdeck","skill-deepgram-webhooks","topic-agent-skills","topic-ai-coding","topic-api-integrations","topic-event-driven","topic-github-webhooks","topic-llm-tools","topic-shopify-webhooks","topic-stripe-webhooks","topic-webhook-security","topic-webhook-signatures","topic-webhooks"],"categories":["webhook-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/hookdeck/webhook-skills/deepgram-webhooks","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add hookdeck/webhook-skills","source_repo":"https://github.com/hookdeck/webhook-skills","install_from":"skills.sh"}},"qualityScore":"0.485","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 71 github stars · SKILL.md body (6,382 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:56:52.716Z","embedding":null,"createdAt":"2026-04-18T22:13:50.684Z","updatedAt":"2026-05-18T18:56:52.716Z","lastSeenAt":"2026-05-18T18:56:52.716Z","tsv":"'-1':375 '-200':518 '-299':519,534 '/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)':671 '/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)':666 '/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)':676 '/hookdeck/webhook-skills/tree/main/skills/github-webhooks)':702 '/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway)':724 '/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks)':693 '/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks)':684 '/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns)':712 '/v1/listen?callback=https://your-domain.com/webhooks/deepgram''':295 '/webhooks/deepgram':105,266,452,478 '0':374 '1':206 '10':523 '2':218 '200':194,533 '30':525 '3000':475 '401':129 '403':167,254 '443':545 '80':544 '8080':546 '8443':548 'account':468 'allow':550 'alongsid':650 'altern':358,360,363,370 'alway':319,531,599 'api':142,151,162,215,249,281,382,388,391,394,412,428,436,440,620 'api.deepgram.com':294 'api.deepgram.com/v1/listen?callback=https://your-domain.com/webhooks/deepgram''':293 'app.post':104 'application/json':108 'asynchron':22,41,67 'attempt':530 'audio':341,348 'audio.wav':291 'audio/wav':287 'auth':220,260,598 'authent':48,113,197,202,257,572,588,624 'author':277 'automat':211,733 'base':309,571 'bash':272,379,462 'basic':98,219,259,597 'behavior':512 'binari':290 'callback':9,19,35,51,60,72,92,225,262,271,485,516,552,617 'channel':345,349,355 'cli':461,473 'code':57 'common':296 'complet':54,97,631 'confid':371,372 'configur':616 'consider':628 'consol':400,424 'console.log':184 'const':119,177,234,239 'contain':149,213 'content':285 'content-typ':284 'creat':330,335,463 'credenti':222 'cryptograph':581 'curl':273 'data':289 'data-binari':288 'debug':507 'deepgram':2,7,14,25,34,45,50,58,78,199,280,299,381,387,399,423,435,476,489,513,565,609,619 'deepgram-webhook':1 'delay':527 'deliveri':732 'descript':318 'develop':454 'dg':116,123,133,147,171,208,230,243,405,576,593 'dg-token':115,122,132,146,170,207,229,242,404,575,592 'dgtoken':120,126,160,240,246,247 'durat':337 'emb':221 'enabl':313 'endpoint':446,556,604 'ensur':553 'environ':377 'error':667,714 'essenti':56 'event':55,297,613,720 'exampl':103,629,630 'expect':141 'express':634 'express.js':102 'express.raw':106 'fail':515 'fastapi':637 'featur':312 'field':317 'gateway':721 'github':698,703 'github-webhook':697 'github.com':665,670,675,683,692,701,711,723 'github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)':669 'github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)':664 'github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)':674 'github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks)':700 'github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway)':722 'github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks)':691 'github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks)':682 'github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns)':710 'guarante':731 'handl':21,52,668,715 'handler':16,36,100,641,645,708,743 'header':118,135,210,232,276,283,578,595 'histori':505 'hmac':582 'hookdeck':460,472,719 'hookdeck-c':471 'hookdeck-event-gateway':718 'https':601 'id':84,164,251,322,438,442 'idempot':663,713 'identifi':144,153,217,324,396,419,426 'immedi':79 'implement':46,632 'import':509 'includ':212 'infrastructur':726 'inspect':501 'instal':459,646,662 'invalid':169,256 'javascript':101,227 'json.parse':179 'key':143,152,163,216,250,282,383,389,392,395,413,429,437,441,653 'length':338 'limit':737 'link':655 'listen':474 'local':453,456,465,493 'logic':673,717 'make':267,385,488 'match':139 'method':198,203,625 'miss':131 'next':238,258 'next.js':635 'non':517 'note':407,510 'npx':470 'number':346 'observ':739 'ok':196 'one':558,652 'origin':157 'overview.md':606 'pars':173 'password@your-domain.com':265 'path':477 'pattern':642,648,709 'payload':305,503 'payment':686 'port':540,543,561 'post':275 'present':320 'prevent':191 'process':17,40,95,181,538 'process.env.deepgram':161,248 'product':644 'provid':70,481,492,587 'queue':730 'rate':736 'rather':579 'receiv':4,64,185 'recommend':233,638 'refer':654 'references/overview.md':607 'references/setup.md':615 'references/verification.md':623 'relat':677 'reli':589 'replac':728 'replay':735 'repositori':704 'req':109,236 'req.body.tostring':180 'req.headers':121,241 'request':77,83,158,269,274,316,321,328,386,434,490,504,621 'requir':469 'res':110,237 'res.status':128,166,193,253 'resourc':605 'respond':80 'restrict':541 'result':24,39,43,66,89,176,302,351,353 'results.channels':357,362,369 'retri':192,511,514,529,672,716,734 'return':127,165,188,252,532 'score':373 'second':343,526 'secret':414 'secur':627 'send':86,130,168,195,255,300 'set':12,32 'setup.md':614 'shopifi':689,694 'shopify-webhook':688 'shown':397,420 'signatur':563,583 'simpl':568 'skill':31,649,660,678 'skill-deepgram-webhooks' 'source-hookdeck' 'status':520,535 'store':695 'stripe':680,685 'stripe-webhook':679 'structur':307 'success':189,537 'support':200 'test':458,497 'text':367 'time':524 'timestamp':331 'token':117,124,134,138,148,172,209,231,244,278,406,570,577,594 'token-bas':569 'tool':508 'topic-agent-skills' 'topic-ai-coding' 'topic-api-integrations' 'topic-event-driven' 'topic-github-webhooks' 'topic-llm-tools' 'topic-shopify-webhooks' 'topic-stripe-webhooks' 'topic-webhook-security' 'topic-webhook-signatures' 'topic-webhooks' 'transcrib':366 'transcript':18,23,38,42,53,65,76,88,175,183,186,301,327,333,352,359,364,612 'transcriptionresult':178,187 'tunnel':466,494 'two':201 'type':107,286,298 'ui':499 'uniqu':323,418 'url':73,93,226,263,292,447,449,482,486,495 'use':10,29,62,114,154,228,401,431,479,557,566,584,600 'usernam':264 'vari':308 'variabl':378 'verif':564 'verifi':6,111,136,403 'verification.md':622 'verifydgtoken':235 'via':573 'web':498 'webhook':3,8,15,26,47,59,99,112,205,304,445,448,457,502,539,555,603,610,640,681,687,690,696,699,705,707,725,742 'webhook-handler-pattern':639,706 'work':656 'yes':329,336,344,350,356,361,368,376 'your-domain.com':451 'your-domain.com/webhooks/deepgram':450","prices":[{"id":"4b10468b-4fbf-411d-b18b-8065c8cc44a6","listingId":"ee399ee8-a4af-4f1c-b737-b892f6f155e9","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"hookdeck","category":"webhook-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:13:50.684Z"}],"sources":[{"listingId":"ee399ee8-a4af-4f1c-b737-b892f6f155e9","source":"github","sourceId":"hookdeck/webhook-skills/deepgram-webhooks","sourceUrl":"https://github.com/hookdeck/webhook-skills/tree/main/skills/deepgram-webhooks","isPrimary":false,"firstSeenAt":"2026-04-18T22:13:50.684Z","lastSeenAt":"2026-05-18T18:56:52.716Z"},{"listingId":"ee399ee8-a4af-4f1c-b737-b892f6f155e9","source":"skills_sh","sourceId":"hookdeck/webhook-skills/deepgram-webhooks","sourceUrl":"https://skills.sh/hookdeck/webhook-skills/deepgram-webhooks","isPrimary":true,"firstSeenAt":"2026-05-07T20:44:38.917Z","lastSeenAt":"2026-05-07T22:42:54.741Z"}],"details":{"listingId":"ee399ee8-a4af-4f1c-b737-b892f6f155e9","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"hookdeck","slug":"deepgram-webhooks","github":{"repo":"hookdeck/webhook-skills","stars":71,"topics":["agent-skills","ai-coding","api-integrations","event-driven","github-webhooks","llm-tools","shopify-webhooks","stripe-webhooks","webhook-security","webhook-signatures","webhooks"],"license":"mit","html_url":"https://github.com/hookdeck/webhook-skills","pushed_at":"2026-05-15T15:30:15Z","description":"Webhook integration skills for AI coding agents (Claude Code, Cursor, Copilot). Step-by-step guidance for setting up webhook receivers, signature verification, and event handling for Stripe, Shopify, GitHub, and more. Built on the Agent Skills specification.","skill_md_sha":"493aaaca65582b536dc5fe363913d6cbc7a571d2","skill_md_path":"skills/deepgram-webhooks/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/hookdeck/webhook-skills/tree/main/skills/deepgram-webhooks"},"layout":"multi","source":"github","category":"webhook-skills","frontmatter":{"name":"deepgram-webhooks","license":"MIT","description":"Receive and verify Deepgram webhooks (callbacks). Use when setting up Deepgram webhook handlers, processing transcription callbacks, or handling asynchronous transcription results."},"skills_sh_url":"https://skills.sh/hookdeck/webhook-skills/deepgram-webhooks"},"updatedAt":"2026-05-18T18:56:52.716Z"}}