用途:该技能面向需要接收 Deepgram 异步转写结果的场景。在转写请求中提供 callback URL 后,Deepgram 会立即返回 request_id,并在处理完成后把结果发送到该回调地址。
主要能力:提供 Express 等框架的 webhook 处理器示例,解析回调体(与同步 /v1/listen 响应结构相同,含 metadata 与 results),提取 request_id、transcript、confidence 等字段;说明两种认证方式——Basic Auth(主要,凭据嵌入回调 URL,以 Authorization: Basic 头发送)与 dg-token 头(辅助,仅在存在时校验,官方称不保证每次回调都发送,不能单独依赖);并给出环境变量配置(DEEPGRAM_API_KEY、DEEPGRAM_CALLBACK_USERNAME、DEEPGRAM_CALLBACK_PASSWORD、DEEPGRAM_API_KEY_ID、WEBHOOK_URL)。
使用方式:发起请求时在 URL 中带 callback 参数,例如 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:password@your-domain.com/webhooks/deepgram'。本地测试可安装 Hookdeck CLI:npx hookdeck-cli listen 3000 deepgram --path /webhooks/deepgram。
限制:Deepgram 不对回调签名(无 HMAC、无时间戳);失败回调(非 200-299)最多重试 10 次,间隔 30 秒;回调仅允许 80、443、8080、8443 端口;建议始终使用 HTTPS。回调体无事件类型字段,results 结构随请求启用的功能变化。
适用场景:搭建 Deepgram 回调处理器、处理异步转写结果、实现回调认证与转写完成事件处理。