elevenlabs-webhooks

ElevenLabs Webhooks

何时使用此技能

• 设置 ElevenLabs webhook 处理程序
• 调试签名验证失败问题
• 了解 ElevenLabs 事件类型和负载
• 处理通话转录事件
• 处理语音移除通知

核心代码

签名验证（SDK — 推荐）

ElevenLabs 建议使用官方的 @elevenlabs/elevenlabs-js SDK 来验证 webhook 并构造事件。请参阅验证 webhook 密钥并构造 webhook 负载。

// Express.js / Node example
const { ElevenLabsClient } = require('@elevenlabs/elevenlabs-js');

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY || 'webhook-only'
});

// In your webhook handler: get raw body and signature header, then:
const event = await elevenlabs.webhooks.constructEvent(rawBody, signatureHeader, process.env.ELEVENLABS_WEBHOOK_SECRET);
// event is the parsed payload; SDK throws on invalid signature

// Next.js example
import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY || 'webhook-only'
});

export async function POST(request: NextRequest) {
  const rawBody = await request.text();
  const signatureHeader = request.headers.get('ElevenLabs-Signature');
  try {
    const event = await elevenlabs.webhooks.constructEvent(
      rawBody,
      signatureHeader,
      process.env.ELEVENLABS_WEBHOOK_SECRET
    );
    // Handle event.type, event.data...
    return new NextResponse('OK', { status: 200 });
  } catch (error) {
    return NextResponse.json({ error: (error as Error).message }, { status: 401 });
  }
}

Python SDK 验证（FastAPI）

import os
from fastapi import FastAPI, Request, HTTPException
from elevenlabs import ElevenLabs
from elevenlabs.errors import BadRequestError

app = FastAPI()
elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY") or "webhook-only")

@app.post("/webhooks/elevenlabs")
async def elevenlabs_webhook(request: Request):
    raw_body = await request.body()
    sig = request.headers.get("ElevenLabs-Signature") or request.headers.get("elevenlabs-signature")
    
    if not sig:
        raise HTTPException(status_code=400, detail="Missing signature header")
    
    try:
        event = elevenlabs.webhooks.construct_event(
            raw_body.decode("utf-8"),
            sig,
            os.environ["ELEVENLABS_WEBHOOK_SECRET"]
        )
        # Handle event["type"], event["data"]...
        return {"status": "ok"}
    except BadRequestError as e:
        raise HTTPException(status_code=401, detail="Invalid signature")

SDK（Node/TypeScript 和 Python）会验证签名、检查时间戳（容差为 30 分钟），并返回解析后的事件。验证失败时会抛出错误；请返回 401 和错误消息。

常见事件类型

事件	触发时机	常见用例
post_call_transcription	通话分析完成时	处理通话洞察、保存转录内容
voice_removal_notice	收到语音即将移除的通知时	通知用户、备份语音数据
voice_removal_notice_withdrawn	语音移除通知取消时	更新用户通知
voice_removed	语音已移除时	清理语音数据、更新 UI

环境变量

ELEVENLABS_WEBHOOK_SECRET=your_webhook_secret_here

本地开发

如需在本地测试 webhook，请安装 Hookdeck CLI：

# Install via npm (recommended)

然后启动隧道：

npx hookdeck-cli listen 3000 elevenlabs --path /webhooks/elevenlabs

无需账户。提供本地隧道和 Web UI，可用于检查请求。

资源

• 概览 - 介绍 ElevenLabs Webhooks 及常见事件类型
• 设置 - 在 ElevenLabs 控制面板中配置 Webhooks 并获取签名密钥
• 验证 - 签名验证详情和注意事项
• Express 示例 - 完整的 Express.js 实现
• Next.js 示例 - Next.js App Router 实现
• FastAPI 示例 - Python FastAPI 实现

推荐：webhook-handler-patterns

我们建议同时安装 webhook-handler-patterns 技能，以了解处理程序顺序、幂等性、错误处理和重试逻辑。关键参考资料（在 GitHub 上打开）：

• 处理程序顺序 — 先验证，再解析，最后以幂等方式处理
• 幂等性 — 防止重复处理
• 错误处理 — 返回代码、日志记录、死信队列
• 重试逻辑 — 提供商重试计划、退避模式

相关技能

• stripe-webhooks - Stripe 支付 webhook 处理
• shopify-webhooks - Shopify 电商 webhook 处理
• github-webhooks - GitHub 仓库 webhook 处理
• resend-webhooks - Resend 邮件 webhook 处理
• chargebee-webhooks - Chargebee 账单 webhook 处理
• clerk-webhooks - Clerk 身份验证 webhook 处理
• openai-webhooks - OpenAI webhook 处理
• paddle-webhooks - Paddle 账单 webhook 处理
• webhook-handler-patterns - 处理程序顺序、幂等性、错误处理、重试逻辑
• hookdeck-event-gateway - 可替代队列的 webhook 基础设施 — 为 webhook 处理程序提供可靠投递、自动重试、重放、速率限制和可观测性

ElevenLabs 官方 SDK 技能

如需调用 ElevenLabs API（文本转语音、转录、Agent），请参阅官方 ElevenLabs Skills。此技能处理相反的方向：接收来自 ElevenLabs 的 webhook。

SDK 警告： JavaScript 始终使用 @elevenlabs/elevenlabs-js。不要使用 npm install elevenlabs（这是过时的 v1.x 软件包）。