OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks
Receive and verify ElevenLabs webhooks. Use when setting up ElevenLabs webhook handlers, debugging signature verification, or handling call transcription events.
npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks
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.
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.
| Event | Triggered When | Common Use Cases |
|---|---|---|
post_call_transcription | Call analysis completed | Process call insights, save transcripts |
voice_removal_notice | Notice that voice will be removed | Notify users, backup voice data |
voice_removal_notice_withdrawn | Voice removal notice cancelled | Update user notifications |
voice_removed | Voice has been removed | Clean up voice data, update UI |
For local webhook testing, install Hookdeck CLI:
Then start the tunnel:
No account required. Provides local tunnel + web UI for inspecting requests.
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):
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-jsfor JavaScript. Do not usenpm install elevenlabs(that's an outdated v1.x package).
// 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 });
}
}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")ELEVENLABS_WEBHOOK_SECRET=your_webhook_secret_here# Install via npm (recommended)
npx hookdeck-cli listen 3000 elevenlabs --path /webhooks/elevenlabs