{"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# Install via npm\nnpm install -g hookdeck-cli\n\n# Or via Homebrew\nbrew install hookdeck/hookdeck/hookdeck\n\n# Create a local tunnel (no account required)\nhookdeck listen 3000 --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.484","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 69 github stars · SKILL.md body (6,471 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-02T06:55:46.219Z","embedding":null,"createdAt":"2026-04-18T22:13:50.684Z","updatedAt":"2026-05-02T06:55:46.219Z","lastSeenAt":"2026-05-02T06:55:46.219Z","tsv":"'-1':375 '-200':529 '-299':530,545 '/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)':682 '/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)':677 '/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)':687 '/hookdeck/webhook-skills/tree/main/skills/github-webhooks)':713 '/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway)':735 '/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks)':704 '/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks)':695 '/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns)':723 '/v1/listen?callback=https://your-domain.com/webhooks/deepgram''':295 '/webhooks/deepgram':105,266,452,489 '0':374 '1':206 '10':534 '2':218 '200':194,544 '30':536 '3000':487 '401':129 '403':167,254 '443':556 '80':555 '8080':557 '8443':559 'account':483 'allow':561 'alongsid':661 'altern':358,360,363,370 'alway':319,542,610 'api':142,151,162,215,249,281,382,388,391,394,412,428,436,440,631 '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':541 'audio':341,348 'audio.wav':291 'audio/wav':287 'auth':220,260,609 'authent':48,113,197,202,257,583,599,635 'author':277 'automat':211,744 'base':309,582 'bash':272,379,462 'basic':98,219,259,608 'behavior':523 'binari':290 'brew':475 'callback':9,19,35,51,60,72,92,225,262,271,496,527,563,628 'channel':345,349,355 'cli':461,471 'code':57 'common':296 'complet':54,97,642 'confid':371,372 'configur':627 'consider':639 'consol':400,424 'console.log':184 'const':119,177,234,239 'contain':149,213 'content':285 'content-typ':284 'creat':330,335,478 'credenti':222 'cryptograph':592 'curl':273 'data':289 'data-binari':288 'debug':518 'deepgram':2,7,14,25,34,45,50,58,78,199,280,299,381,387,399,423,435,500,524,576,620,630 'deepgram-webhook':1 'delay':538 'deliveri':743 'descript':318 'develop':454 'dg':116,123,133,147,171,208,230,243,405,587,604 'dg-token':115,122,132,146,170,207,229,242,404,586,603 'dgtoken':120,126,160,240,246,247 'durat':337 'emb':221 'enabl':313 'endpoint':446,567,615 'ensur':564 'environ':377 'error':678,725 'essenti':56 'event':55,297,624,731 'exampl':103,640,641 'expect':141 'express':645 'express.js':102 'express.raw':106 'fail':526 'fastapi':648 'featur':312 'field':317 'g':468 'gateway':732 'github':709,714 'github-webhook':708 'github.com':676,681,686,694,703,712,722,734 'github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)':680 'github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)':675 'github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)':685 'github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks)':711 'github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway)':733 'github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks)':702 'github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks)':693 'github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns)':721 'guarante':742 'handl':21,52,679,726 'handler':16,36,100,652,656,719,754 'header':118,135,210,232,276,283,589,606 'histori':516 'hmac':593 'homebrew':474 'hookdeck':460,470,485,730 'hookdeck-c':469 'hookdeck-event-gateway':729 'hookdeck/hookdeck/hookdeck':477 'https':612 'id':84,164,251,322,438,442 'idempot':674,724 'identifi':144,153,217,324,396,419,426 'immedi':79 'implement':46,643 'import':520 'includ':212 'infrastructur':737 'inspect':512 'instal':459,463,467,476,657,673 'invalid':169,256 'javascript':101,227 'json.parse':179 'key':143,152,163,216,250,282,383,389,392,395,413,429,437,441,664 'length':338 'limit':748 'link':666 'listen':486 'local':453,456,480,504 'logic':684,728 'make':267,385,499 'match':139 'method':198,203,636 'miss':131 'next':238,258 'next.js':646 'non':528 'note':407,521 'npm':465,466 'number':346 'observ':750 'ok':196 'one':569,663 'origin':157 'overview.md':617 'pars':173 'password@your-domain.com':265 'path':488 'pattern':653,659,720 'payload':305,514 'payment':697 'port':551,554,572 'post':275 'present':320 'prevent':191 'process':17,40,95,181,549 'process.env.deepgram':161,248 'product':655 'provid':70,492,503,598 'queue':741 'rate':747 'rather':590 'receiv':4,64,185 'recommend':233,649 'refer':665 'references/overview.md':618 'references/setup.md':626 'references/verification.md':634 'relat':688 'reli':600 'replac':739 'replay':746 'repositori':715 'req':109,236 'req.body.tostring':180 'req.headers':121,241 'request':77,83,158,269,274,316,321,328,386,434,501,515,632 'requir':484 'res':110,237 'res.status':128,166,193,253 'resourc':616 'respond':80 'restrict':552 'result':24,39,43,66,89,176,302,351,353 'results.channels':357,362,369 'retri':192,522,525,540,683,727,745 'return':127,165,188,252,543 'score':373 'second':343,537 'secret':414 'secur':638 'send':86,130,168,195,255,300 'set':12,32 'setup.md':625 'shopifi':700,705 'shopify-webhook':699 'shown':397,420 'signatur':574,594 'simpl':579 'skill':31,660,671,689 'skill-deepgram-webhooks' 'source-hookdeck' 'status':531,546 'store':706 'stripe':691,696 'stripe-webhook':690 'structur':307 'success':189,548 'support':200 'test':458,508 'text':367 'time':535 'timestamp':331 'token':117,124,134,138,148,172,209,231,244,278,406,581,588,605 'token-bas':580 'tool':519 '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,623 'transcriptionresult':178,187 'tunnel':481,505 'two':201 'type':107,286,298 'ui':510 'uniqu':323,418 'url':73,93,226,263,292,447,449,493,497,506 'use':10,29,62,114,154,228,401,431,490,568,577,595,611 'usernam':264 'vari':308 'variabl':378 'verif':575 'verifi':6,111,136,403 'verification.md':633 'verifydgtoken':235 'via':464,473,584 'web':509 'webhook':3,8,15,26,47,59,99,112,205,304,445,448,457,513,550,566,614,621,651,692,698,701,707,710,716,718,736,753 'webhook-handler-pattern':650,717 'work':667 '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-02T06:55:46.219Z"}],"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":69,"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-02-25T14:00:40Z","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":"af409918ac2302fbe07da102ab47cf77732be845","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-02T06:55:46.219Z"}}