Back to Details

elevenlabs-webhooks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ElevenLabs Webhooks

ElevenLabs Webhook

When to Use This Skill

适用场景

  • Setting up ElevenLabs webhook handlers
  • Debugging signature verification failures
  • Understanding ElevenLabs event types and payloads
  • Processing call transcription events
  • Handling voice removal notifications
  • 搭建ElevenLabs Webhook处理器
  • 调试签名验证失败问题
  • 了解ElevenLabs事件类型与负载
  • 处理通话转录事件
  • 处理语音移除通知

Essential Code

核心代码示例

Signature Verification (SDK — Recommended)

签名验证（推荐使用SDK）

ElevenLabs recommends using the official 
@elevenlabs/elevenlabs-js
SDK for webhook verification and event construction. See Verify the webhook secret and construct the webhook payload.
javascript
// 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
typescript
// 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 });
  }
}
ElevenLabs 推荐使用官方 
@elevenlabs/elevenlabs-js
SDK 进行Webhook验证和事件解析。详情请查看验证Webhook密钥并构造Webhook负载。
javascript
// 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
typescript
// 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 Verification (FastAPI)

Python SDK 验证（FastAPI）

python
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")
The SDK (Node/TypeScript and Python) verifies the signature, validates the timestamp (30-minute tolerance), and returns the parsed event. On failure it throws; return 401 and the error message.
python
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")
Node/TypeScript和Python版本的SDK会验证签名、校验时间戳（允许30分钟误差），并返回解析后的事件。验证失败时会抛出异常；此时应返回401状态码及错误信息。

Common Event Types

常见事件类型

EventTriggered WhenCommon Use Cases
post_call_transcription
Call analysis completedProcess call insights, save transcripts
voice_removal_notice
Notice that voice will be removedNotify users, backup voice data
voice_removal_notice_withdrawn
Voice removal notice cancelledUpdate user notifications
voice_removed
Voice has been removedClean up voice data, update UI
事件触发时机常见应用场景
post_call_transcription
通话分析完成后处理通话洞察、保存转录文本
voice_removal_notice
收到语音将被移除的通知时通知用户、备份语音数据
voice_removal_notice_withdrawn
语音移除通知被取消时更新用户通知
voice_removed
语音已被移除时清理语音数据、更新UI

Environment Variables

环境变量

bash
ELEVENLABS_WEBHOOK_SECRET=your_webhook_secret_here
bash
ELEVENLABS_WEBHOOK_SECRET=your_webhook_secret_here

Local Development

本地开发调试

For local webhook testing, install Hookdeck CLI:
bash
undefined
如需在本地测试Webhook，请安装Hookdeck CLI：
bash
undefined

Install via npm (recommended)

Install via npm (recommended)

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

Or via Homebrew

Or via Homebrew

brew install hookdeck/hookdeck/hookdeck

Then start the tunnel:

```bash
hookdeck listen 3000 --path /webhooks/elevenlabs
No account required. Provides local tunnel + web UI for inspecting requests.
brew install hookdeck/hookdeck/hookdeck

然后启动隧道：

```bash
hookdeck listen 3000 --path /webhooks/elevenlabs
无需注册账号。提供本地隧道及Web界面用于查看请求详情。

Resources

相关资源

  • Overview - What ElevenLabs webhooks are, common event types
  • Setup - Configure webhooks in ElevenLabs dashboard, get signing secret
  • Verification - Signature verification details and gotchas
  • Express Example - Complete Express.js implementation
  • Next.js Example - Next.js App Router implementation
  • FastAPI Example - Python FastAPI implementation
  • 概述 - ElevenLabs Webhook是什么、常见事件类型
  • 配置 - 在ElevenLabs控制台配置Webhook、获取签名密钥
  • 验证 - 签名验证细节与注意事项
  • Express示例 - 完整的Express.js实现
  • Next.js示例 - Next.js App Router实现
  • FastAPI示例 - Python FastAPI实现

Recommended: webhook-handler-patterns

推荐搭配：webhook-handler-patterns

We recommend installing the webhook-handler-patterns skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):
我们推荐搭配安装webhook-handler-patterns技能，以获取处理器流程、幂等性、错误处理和重试逻辑的最佳实践。关键参考文档（可在GitHub查看）：

Related Skills

相关技能

Official ElevenLabs SDK Skills

ElevenLabs 官方SDK技能

For making API calls TO ElevenLabs (text-to-speech, transcription, agents), see the official ElevenLabs Skills. This skill handles the opposite direction: receiving webhooks FROM ElevenLabs.
SDK Warning: Always use 
@elevenlabs/elevenlabs-js
for JavaScript. Do not use 
npm install elevenlabs
(that's an outdated v1.x package).
如需调用ElevenLabs API（文本转语音、转录、Agent等），请查看官方ElevenLabs Skills。本技能处理的是反向场景：接收来自ElevenLabs的Webhook。
SDK 注意事项： JavaScript环境下请始终使用 
@elevenlabs/elevenlabs-js
。不要使用 
npm install elevenlabs
（该包为过时的v1.x版本）。