#ElevenLabs Webhooks ## 何时使用此技能 * 设置 ElevenLabs webhook 处理程序 * 调试签名验证失败的问题 * 了解 ElevenLabs 事件类型和有效负载 * 处理通话转录事件 * 处理语音删除通知 ## 基本代码 ### 签名验证（SDK — 推荐） ElevenLabs 建议使用官方的“@elevenlabs/elevenlabs-js” SDK 进行 webhook 验证和事件构建。请参阅[验证 Webhook 密钥并构建 Webhook 负载]()。 // Express.js / 节点示例 const { ElevenLabsClient } = require('@elevenlabs/elevenlabs-js'); 常量 11labs = 新 11LabsClient({ apiKey: process.env.ELEVENLABS_API_KEY || “仅限网络钩子” }); // 在您的 webhook 处理程序中：获取原始正文和签名标头，然后： const event =等待 111labs.webhooks.constructEvent(rawBody,signatureHeader,process.env.ELEVENLABS_WEBHOOK_SECRET); // event 是解析后的有效负载； SDK 抛出无效签名 // Next.js 示例从'@elevenlabs/elevenlabs-js'导入{ElevenLabsClient}；常量 11labs = 新 11LabsClient({ apiKey: process.env.ELEVENLABS_API_KEY || “仅限网络钩子” }); 导出异步函数 POST(request: NextRequest) { const rawBody = 等待 request.text(); const SignatureHeader = request.headers.get('ElevenLabs-Signature'); 尝试{ const 事件 = 等待 111labs.webhooks.constructEvent( 原始身体，签名标头， process.env.ELEVENLABS_WEBHOOK_SECRET ）； // 处理事件.类型、事件.数据... 返回新的 NextResponse('确定', { 状态: 200 }); } 捕获（错误）{ return NextResponse.json({ error: (error as Error).message }, { status: 401 }); } } ### Python SDK 验证（FastAPI）导入操作系统从 fastapi 导入 FastAPI、请求、HTTPException 从 11labs 导入 11Labs 从 11labs.errors 导入 BadRequestError 应用程序 = FastAPI() ElevenLabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY") 或 "仅 webhook") @app.post(“/webhooks/elevenlabs”) 异步def Elevenlabs_webhook（请求：请求）： raw_body = 等待 request.body() sig = request.headers.get("ElevenLabs-Signature") 或 request.headers.get("elevenlabs-signature") 如果没有签名：引发HTTPException（status_code = 400，detail =“缺少签名标头”）尝试：事件 = 111labs.webhooks.construct_event( raw_body.decode("utf-8"), 签名， os.environ["ELEVENLABS_WEBHOOK_SECRET"] ） # 处理事件[“类型”]、事件[“数据”]... 返回{“状态”：“确定”} 除了 BadRequestError 为 e：引发HTTPException（status_code = 401，detail =“无效签名”） SDK（Node/TypeScript 和 Python）验证签名、验证时间戳（30 分钟容差）并返回解析的事件。失败时抛出；返回 401 和错误消息。 ## 常见事件类型活动 |触发时间 |常见用例 ---|---|--- `post_call_transcription` |通话分析完成 |处理通话见解，保存记录 `语音删除通知` |请注意，语音将被删除 |通知用户，备份语音数据 `voice_removal_notice_withdrawn` |语音删除通知取消 |更新用户通知 `语音_已删除` |语音已被删除 |清理语音数据，更新UI ## 环境变量 ELEVENLABS_WEBHOOK_SECRET=your_webhook_secret_here ## 本地发展对于本地 webhook 测试，请安装 Hookdeck CLI： # 通过 npm 安装（推荐） npm install -g hookdeck-cli # 或者通过自制程序酿造安装hookdeck/hookdeck/hookdeck 然后启动隧道： hookdeck Listen 3000 --path /webhooks/elevenlabs 无需帐户。提供本地隧道 + Web UI 用于检查请求。 ## 资源 * [概述]() \- ElevenLabs webhooks 是什么，常见事件类型 * [Setup]() \- 在 ElevenLabs 仪表板中配置 webhooks，获取签名密钥 * [验证]() \- 签名验证详细信息和陷阱 * [Express 示例]() \- 完整的 Express.js 实现 * [Next.js 示例]() \- Next.js 应用路由器实现 * [FastAPI 示例]() \- Python FastAPI 实现 ## 推荐：webhook-handler-patterns 我们建议将 [webhook-handler-patterns]() 技能与此技能一起安装，以实现处理程序序列、幂等性、错误处理和重试逻辑。主要参考文献（在 GitHub 上打开）： * [处理程序序列]() - 首先验证，第二解析，第三处理幂等 * [幂等性]() — 防止重复处理 * [错误处理]() — 返回代码、日志记录、死信队列 * [重试逻辑]() — 提供者重试计划、退避模式 ## 相关技能 * [stripe-webhooks]() \- Stripe 支付 webhook 处理 * [shopify-webhooks]() \- Shopify 电子商务 webhook 处理 * [github-webhooks]() \- GitHub 存储库 webhook 处理 * [resend-webhooks]() \- 重新发送电子邮件 webhook 处理 * [chargebee-webhooks]() \- Chargebee 计费 webhook 处理 * [clerk-webhooks]() \- Clerk auth webhook 处理 * [openai-webhooks]() \- OpenAI webhook 处理 * [paddle-webhooks]() \- Paddle 计费 webhook 处理 * [webhook-handler-patterns]() \- 处理程序序列、幂等性、错误处理、重试逻辑 * [hookdeck-event-gateway]() \- 取代队列的 Webhook 基础设施 — 保证交付、自动重试、重播、速率限制和 Webhook 处理程序的可观察性 ## 官方ElevenLabs SDK技能如需向 ElevenLabs 进行 API 调用（文本转语音、转录、代理），请参阅官方 [ElevenLabs Skills]()。该技能处理相反的方向：从 ElevenLabs 接收 webhook。 > **SDK 警告：** 对于 JavaScript，请始终使用 `@elevenlabs/elevenlabs-js`。不要使用“npm install Elevenlabs”（这是一个过时的 v1.x 包）。

Elevenlabs Webhook

包含技能