Back to Details

deepgram-webhooks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deepgram Webhooks

Deepgram Webhooks

When to Use This Skill

何时使用该Skill

  • Setting up Deepgram callback handlers for transcription results
  • Processing asynchronous transcription results from Deepgram
  • Implementing webhook authentication for Deepgram callbacks
  • Handling transcription completion events
  • 为转录结果设置Deepgram回调处理器
  • 处理来自Deepgram的异步转录结果
  • 为Deepgram回调实现webhook身份验证
  • 处理转录完成事件

Essential Code

核心代码

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.
Deepgram webhook（回调）用于异步接收转录结果。当你在转录请求中提供回调URL时，Deepgram会立即返回一个
request_id
，并在处理完成后将转录结果发送到你的回调URL。

Basic Webhook Handler

基础Webhook处理器

javascript
// Express.js example
app.post('/webhooks/deepgram', express.raw({ type: 'application/json' }), (req, res) => {
  // Verify webhook authenticity using dg-token header
  const dgToken = req.headers['dg-token'];

  if (!dgToken) {
    return res.status(401).send('Missing dg-token header');
  }

  // Verify the token matches your expected API Key Identifier
  // The dg-token contains the API Key Identifier used in the original request
  if (dgToken !== process.env.DEEPGRAM_API_KEY_ID) {
    return res.status(403).send('Invalid dg-token');
  }

  // Parse the transcription result
  const transcriptionResult = JSON.parse(req.body.toString());

  // Process the transcription
  console.log('Received transcription:', transcriptionResult);

  // Return success to prevent retries
  res.status(200).send('OK');
});
javascript
// Express.js example
app.post('/webhooks/deepgram', express.raw({ type: 'application/json' }), (req, res) => {
  // Verify webhook authenticity using dg-token header
  const dgToken = req.headers['dg-token'];

  if (!dgToken) {
    return res.status(401).send('Missing dg-token header');
  }

  // Verify the token matches your expected API Key Identifier
  // The dg-token contains the API Key Identifier used in the original request
  if (dgToken !== process.env.DEEPGRAM_API_KEY_ID) {
    return res.status(403).send('Invalid dg-token');
  }

  // Parse the transcription result
  const transcriptionResult = JSON.parse(req.body.toString());

  // Process the transcription
  console.log('Received transcription:', transcriptionResult);

  // Return success to prevent retries
  res.status(200).send('OK');
});

Authentication Methods

身份验证方式

Deepgram supports two authentication methods for webhooks:
  1. dg-token Header: Automatically included, contains the API Key Identifier
  2. Basic Auth: Embed credentials in the callback URL
javascript
// Using dg-token header (recommended)
const verifyDgToken = (req, res, next) => {
  const dgToken = req.headers['dg-token'];

  if (!dgToken || dgToken !== process.env.DEEPGRAM_API_KEY_ID) {
    return res.status(403).send('Invalid authentication');
  }

  next();
};

// Basic Auth in callback URL
// https://username:password@your-domain.com/webhooks/deepgram
Deepgram为webhook支持两种身份验证方式：
  1. dg-token Header: 自动包含，包含API密钥标识符
  2. Basic Auth: 在回调URL中嵌入凭证
javascript
// Using dg-token header (recommended)
const verifyDgToken = (req, res, next) => {
  const dgToken = req.headers['dg-token'];

  if (!dgToken || dgToken !== process.env.DEEPGRAM_API_KEY_ID) {
    return res.status(403).send('Invalid authentication');
  }

  next();
};

// Basic Auth in callback URL
// https://username:password@your-domain.com/webhooks/deepgram

Making a Request with Callback

发起带回调的请求

bash
curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @audio.wav \
  --url 'https://api.deepgram.com/v1/listen?callback=https://your-domain.com/webhooks/deepgram'
bash
curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @audio.wav \
  --url 'https://api.deepgram.com/v1/listen?callback=https://your-domain.com/webhooks/deepgram'

Common Event Types

常见事件类型

Deepgram sends transcription results as webhook payloads. The structure varies based on the features enabled in your request:
FieldDescriptionAlways Present
request_id
Unique identifier for the transcription requestYes
created
Timestamp when transcription was createdYes
duration
Length of the audio in secondsYes
channels
Number of audio channelsYes
results
Transcription results by channelYes
results.channels[].alternatives
Transcription alternativesYes
results.channels[].alternatives[].transcript
The transcribed textYes
results.channels[].alternatives[].confidence
Confidence score (0-1)Yes
Deepgram将转录结果作为webhook负载发送。其结构根据请求中启用的功能而有所不同：
字段描述是否始终存在
request_id
转录请求的唯一标识符是
created
转录创建的时间戳是
duration
音频时长（秒）是
channels
音频声道数是
results
按声道划分的转录结果是
results.channels[].alternatives
转录备选结果是
results.channels[].alternatives[].transcript
转录文本是
results.channels[].alternatives[].confidence
置信度分数（0-1）是

Environment Variables

环境变量

bash
undefined
bash
undefined

Your Deepgram API Key (for making requests)

Your Deepgram API Key (for making requests)

DEEPGRAM_API_KEY=your_api_key_here
DEEPGRAM_API_KEY=your_api_key_here

API Key Identifier (shown in Deepgram console, used to verify dg-token)

API Key Identifier (shown in Deepgram console, used to verify dg-token)

Note: This is NOT your API Key secret - it's a unique identifier shown

Note: This is NOT your API Key secret - it's a unique identifier shown

in the Deepgram console that identifies which API key was used for a request

in the Deepgram console that identifies which API key was used for a request

DEEPGRAM_API_KEY_ID=your_api_key_id_here
DEEPGRAM_API_KEY_ID=your_api_key_id_here

Your webhook endpoint URL

Your webhook endpoint URL

WEBHOOK_URL=https://your-domain.com/webhooks/deepgram
undefined
WEBHOOK_URL=https://your-domain.com/webhooks/deepgram
undefined

Local Development

本地开发

For local webhook testing, install Hookdeck CLI:
bash
undefined
对于本地webhook测试，请安装Hookdeck CLI：
bash
undefined

Install via npm

Install via npm

npm install -g hookdeck-cli
npm install -g hookdeck-cli

Or via Homebrew

Or via Homebrew

brew install hookdeck/hookdeck/hookdeck
brew install hookdeck/hookdeck/hookdeck

Create a local tunnel (no account required)

Create a local tunnel (no account required)

hookdeck listen 3000 --path /webhooks/deepgram
hookdeck listen 3000 --path /webhooks/deepgram

Use the provided URL as your callback URL when making Deepgram requests

Use the provided URL as your callback URL when making Deepgram requests


This provides:
- Local tunnel URL for testing
- Web UI for inspecting webhook payloads
- Request history and debugging tools

它提供以下功能：
- 用于测试的本地隧道URL
- 用于查看webhook负载的Web界面
- 请求历史和调试工具

Important Notes

重要说明

Retry Behavior

重试机制

  • Deepgram retries failed callbacks (non-200-299 status) up to 10 times
  • 30-second delay between retry attempts
  • Always return 200-299 status for successfully processed webhooks
  • Deepgram会对失败的回调（非200-299状态码）最多重试10次
  • 重试间隔为30秒
  • 处理成功的webhook请始终返回200-299状态码

Port Restrictions

端口限制

  • Only ports 80, 443, 8080, and 8443 are allowed for callbacks
  • Ensure your webhook endpoint uses one of these ports
  • 回调仅允许使用80、443、8080和8443端口
  • 确保你的webhook端点使用这些端口之一

No Signature Verification

无签名验证

  • Deepgram uses a simple token-based authentication via the dg-token header rather than cryptographic HMAC signatures used by other providers
  • Authentication relies on the 
    dg-token
    header or Basic Auth
  • Always use HTTPS for webhook endpoints
  • Deepgram通过dg-token头使用简单的基于令牌的身份验证，而非其他服务商使用的加密HMAC签名
  • 身份验证依赖
    dg-token
    头或Basic Auth
  • webhook端点请始终使用HTTPS

Resources

相关资源

  • overview.md - What Deepgram webhooks are, transcription events
  • setup.md - Configure callbacks in Deepgram API requests
  • verification.md - Authentication methods and security considerations
  • examples/ - Complete implementations for Express, Next.js, and FastAPI
  • overview.md - 介绍Deepgram webhook是什么以及转录事件
  • setup.md - 配置Deepgram API请求中的回调
  • verification.md - 身份验证方式和安全注意事项
  • examples/ - Express、Next.js和FastAPI的完整实现示例

Recommended: webhook-handler-patterns

推荐：webhook-handler-patterns

For production handlers, install the patterns skill alongside this one. Key references (links work when only this skill is installed):
对于生产环境的处理器，请同时安装该pattern skill。核心参考链接（仅安装此Skill时链接可用）：

Related Skills

相关Skill