deepgram-webhooks

Deepgram Webhook

このスキルを使用する場面

• 文字起こし結果を受信する Deepgram コールバックハンドラーを設定するとき
• Deepgram から非同期で送信される文字起こし結果を処理するとき
• Deepgram コールバックの Webhook 認証を実装するとき
• 文字起こし完了イベントを処理するとき

基本的なコード

// Express.js example
const crypto = require('crypto');

function safeEqual(a, b) {
  const ab = Buffer.from(a || '', 'utf8');
  const bb = Buffer.from(b || '', 'utf8');
  return ab.length === bb.length && crypto.timingSafeEqual(ab, bb);
}

app.post('/webhooks/deepgram', express.raw({ type: 'application/json' }), (req, res) => {
  // 1. Primary check: Basic Auth credentials you embedded in the callback URL
  //    (https://user:[email protected]/webhooks/deepgram)
  const auth = req.headers['authorization'] || '';
  const decoded = auth.startsWith('Basic ')
    ? Buffer.from(auth.slice(6), 'base64').toString('utf8')
    : '';
  const sep = decoded.indexOf(':');
  if (
    sep === -1 ||
    !safeEqual(decoded.slice(0, sep), process.env.DEEPGRAM_CALLBACK_USERNAME) ||
    !safeEqual(decoded.slice(sep + 1), process.env.DEEPGRAM_CALLBACK_PASSWORD)
  ) {
    return res.status(401).send('Unauthorized');
  }

  // 2. Supplementary check: dg-token is NOT sent on every callback,
  //    so only compare it when it is present
  const dgToken = req.headers['dg-token'];
  if (dgToken && process.env.DEEPGRAM_API_KEY_ID && !safeEqual(dgToken, process.env.DEEPGRAM_API_KEY_ID)) {
    return res.status(403).send('Invalid dg-token');
  }

  // The callback body is the normal /v1/listen response: { metadata, results }
  const payload = JSON.parse(req.body.toString());
  const requestId = payload.metadata?.request_id;
  const transcript = payload.results?.channels?.[0]?.alternatives?.[0]?.transcript;
  console.log('Received transcription:', requestId, transcript);

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

認証方法

Deepgram では、コールバックを認証する方法として次の 2 つが記載されています。

1. Basic Auth（主要な方法）：コールバック URL に認証情報を埋め込みます。Deepgram は Authorization: Basic ヘッダーを送信します
2. dg-token ヘッダー（補助的な方法）：このヘッダーがある場合、リクエストを送信した API キーの識別子が含まれます。Deepgram のドキュメントには「すべてのコールバックリクエストに含まれるとは限らない」と記載されているため、これだけに依存しないでください

// Basic Auth in callback URL (percent-encode special characters in the credentials)
// https://username:[email protected]/webhooks/deepgram

// dg-token: check only when present
const dgToken = req.headers['dg-token'];
if (dgToken && dgToken !== process.env.DEEPGRAM_API_KEY_ID) {
  return res.status(403).send('Invalid dg-token');
}

コールバックを指定してリクエストを送信する

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://username:[email protected]/webhooks/deepgram'

一般的なイベントタイプ

Deepgram のコールバックにはイベントタイプのフィールドがありません。本文は、同期的な /v1/listen リクエストが返すものと同じ JSON で、metadata オブジェクトと results オブジェクトが含まれます。results の構造は、リクエストで有効にした機能によって異なります。

フィールド	説明	常に存在する
metadata.request_id	文字起こしリクエストの一意の識別子（送信時に返される request_id と一致します）	はい
metadata.created	文字起こしが作成された時刻	はい
metadata.duration	音声の長さ（秒）	はい
metadata.channels	音声チャンネル数	はい
metadata.extra	extra=KEY:VALUE で渡したキーと値のペア	extra を送信した場合のみ
results.channels[].alternatives	文字起こしの候補	はい
results.channels[].alternatives[].transcript	文字起こしされたテキスト	はい
results.channels[].alternatives[].confidence	信頼度スコア（0～1）	はい

環境変数

# Your Deepgram API Key (for making requests)
DEEPGRAM_API_KEY=your_api_key_here

# Basic Auth credentials you embed in the callback URL (primary check)
DEEPGRAM_CALLBACK_USERNAME=your_callback_username
DEEPGRAM_CALLBACK_PASSWORD=your_callback_password

# Optional: API Key Identifier, used to check the dg-token header when present
# 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
DEEPGRAM_API_KEY_ID=your_api_key_id_here

# Your webhook endpoint URL
WEBHOOK_URL=https://your-domain.com/webhooks/deepgram

ローカル開発

ローカルで Webhook をテストするには、Hookdeck CLI をインストールしてください。

# Create a local tunnel (no account required)
npx hookdeck-cli listen 3000 deepgram --path /webhooks/deepgram

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

次の機能を利用できます。

• テスト用のローカルトンネル URL
• Webhook ペイロードを確認する Web UI
• リクエスト履歴とデバッグツール

重要な注意事項

再試行の動作

• Deepgram は失敗したコールバック（200～299 以外のステータス）を最大 10 回再試行します
• 再試行の間隔は 30 秒です
• 正常に処理された Webhook には、必ず 200～299 のステータスを返してください

ポートの制限

• コールバックに使用できるポートは 80、443、8080、8443 のみです
• Webhook エンドポイントがこれらのいずれかのポートを使用していることを確認してください

署名検証なし

• Deepgram はコールバックに署名を付与しません（HMAC もタイムスタンプもありません）
• コールバック URL に埋め込んだ Basic Auth の認証情報を使って認証してください。dg-token ヘッダーはすべてのコールバックに送信されるわけではないため、補助的な確認にとどめてください
• Webhook エンドポイントには必ず HTTPS を使用してください

リソース

• overview.md - Deepgram Webhook の概要と文字起こしイベント
• setup.md - Deepgram API リクエストでのコールバック設定
• verification.md - 認証方法とセキュリティ上の考慮事項
• examples/ - Express、Next.js、FastAPI の完全な実装例

推奨：webhook-handler-patterns

本番環境のハンドラー向けに、このスキルと合わせてパターンスキルをインストールしてください。主なリファレンス（このスキルのみをインストールしている場合もリンクは機能します）。

• 冪等性
• エラー処理
• 再試行ロジック

関連スキル

• stripe-webhooks - Stripe の決済 Webhook
• shopify-webhooks - Shopify ストアの Webhook
• github-webhooks - GitHub リポジトリの Webhook
• webhook-handler-patterns - 冪等性、エラー処理、再試行ロジック
• hookdeck-event-gateway - キューに代わる Webhook インフラストラクチャです。Webhook ハンドラーへの配信保証、自動再試行、再生、レート制限、可観測性を提供します