elevenlabs-webhooks（十一实验室网络钩子）

ElevenLabs Webhooks

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

Essential Code

Signature Verification (SDK — Recommended)

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.

// 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 Verification (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")

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.

Common Event Types

Environment Variables

ELEVENLABS_WEBHOOK_SECRET=your_webhook_secret_here

Local Development

For local webhook testing, install Hookdeck CLI:

# Install via npm (recommended)
npm install -g hookdeck-cli

# Or via Homebrew
brew install hookdeck/hookdeck/hookdeck

Then start the tunnel:

hookdeck listen 3000 --path /webhooks/elevenlabs

No account required. Provides local tunnel + web UI for inspecting requests.

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

Recommended: 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):

• Handler sequence — Verify first, parse second, handle idempotently third
• Idempotency — Prevent duplicate processing
• Error handling — Return codes, logging, dead letter queues
• Retry logic — Provider retry schedules, backoff patterns

Related Skills

• stripe-webhooks - Stripe payment webhook handling
• shopify-webhooks - Shopify e-commerce webhook handling
• github-webhooks - GitHub repository webhook handling
• resend-webhooks - Resend email webhook handling
• chargebee-webhooks - Chargebee billing webhook handling
• clerk-webhooks - Clerk auth webhook handling
• openai-webhooks - OpenAI webhook handling
• paddle-webhooks - Paddle billing webhook handling
• webhook-handler-patterns - Handler sequence, idempotency, error handling, retry logic
• hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

Official ElevenLabs SDK Skills

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).