elevenlabs-webhooks — Claude Code skill: what it does & install
Teaches your coding assistant how to verify and handle ElevenLabs webhooks. Useful when implementing call transcript handlers or debugging signature validation.
MIT 237 installs ★ 103 updated 2026-10-22
npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks -a claude-codeWhat elevenlabs-webhooks does
This skill guides AI assistants through receiving ElevenLabs webhooks in Next.js and FastAPI. It relies on the official @elevenlabs/elevenlabs-js and Python elevenlabs packages. Instead of writing custom HMAC algorithms, the assistant uses constructEvent to parse the payload and validate the ElevenLabs-Signature header.
Verification fails if the endpoint parses JSON before signature validation. The SDK requires unparsed raw body bytes and the ELEVENLABS_WEBHOOK_SECRET environment variable. The validation logic also enforces a 30-minute timestamp tolerance window.
The reference covers events like post_call_transcription and voice_removed. For local development, it suggests using hookdeck-cli to route incoming webhooks directly to port 3000 without creating an account.
What it helps with
- verify ElevenLabs-Signature headers using official SDKs
- process post_call_transcription events from completed calls
- handle voice removal lifecycle notifications
- inspect incoming webhooks locally using hookdeck-cli
Example prompts for the agent
- Create a Next.js App Router route that validates ElevenLabs webhooks with constructEvent.
- Write a FastAPI webhook receiver for post_call_transcription events using the elevenlabs Python SDK.
- Show how to tunnel ElevenLabs webhooks to localhost:3000 using Hookdeck CLI.
How to install elevenlabs-webhooks
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks -a claude-code2Manually: put the files in place
~/.claude/skills/elevenlabs-webhooks/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/elevenlabs-webhooks/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks -a codex2Manually: put the files in place
.agents/skills/elevenlabs-webhooks/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks -a cursor2Manually: put the files in place
.cursor/skills/elevenlabs-webhooks/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills skills/elevenlabs-webhooks2Manually: put the files in place
.github/skills/elevenlabs-webhooks/SKILL.md1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks -a gemini-cli2Platform CLI
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/elevenlabs-webhooksManually: put the files in place
.devin/skills/elevenlabs-webhooks/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about elevenlabs-webhooks
How to install elevenlabs-webhooks in Claude Code?
Run npx skills add hookdeck/webhook-skills --skill elevenlabs-webhooks -a claude-code. The file will be installed to ~/.claude/skills/elevenlabs-webhooks/SKILL.md.
What does elevenlabs-webhooks do?
It provides implementation patterns and code snippets for handling ElevenLabs webhook events. Your AI agent learns how to verify signatures and parse event payloads correctly.
What timestamp tolerance is allowed for webhook signatures?
The official SDK checks timestamps with a 30-minute tolerance limit. If an event timestamp differs by more than 30 minutes, verification fails with a bad request error.
Source text
SKILL.md · MIT
---
name: elevenlabs-webhooks
description: >
Receive and verify ElevenLabs webhooks. Use when setting up ElevenLabs webhook
handlers, debugging signature verification, or handling call transcription events.
license: MIT
metadata:
author: hookdeck
version: "0.1.0"
repository: https://github.com/hookdeck/webhook-skills
---
# 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](https://elevenlabs.io/docs/agents-platform/guides/integrations/upstash-redis#verify-the-webhook-secret-and-consrtuct-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 });
}
}
```
### Python SDK Verification (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.
## Common Event Types
| 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 |
## Environment Variables
```bash
ELEVENLABS_WEBHOOK_SECRET=your_webhook_secret_here
```
## Local Development
For local webhook testing, install Hookdeck CLI:
```bash
# Install via npm (recommended)
```
Then start the tunnel:
```bash
npx hookdeck-cli listen 3000 elevenlabs --path /webhooks/elevenlabs
```
No account required. Provides local tunnel + web UI for inspecting requests.
## Resources
- [Overview](references/overview.md) - What ElevenLabs webhooks are, common event types
- [Setup](references/setup.md) - Configure webhooks in ElevenLabs dashboard, get signing secret
- [Verification](references/verification.md) - Signature verification details and gotchas
- [Express Example](examples/express/) - Complete Express.js implementation
- [Next.js Example](examples/nextjs/) - Next.js App Router implementation
- [FastAPI Example](examples/fastapi/) - Python FastAPI implementation
## Recommended: webhook-handler-patterns
We recommend installing the [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):
- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md) — Verify first, parse second, handle idempotently third
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md) — Prevent duplicate processing
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md) — Return codes, logging, dead letter queues
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md) — Provider retry schedules, backoff patterns
## Related Skills
- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe payment webhook handling
- [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify e-commerce webhook handling
- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository webhook handling
- [resend-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/resend-webhooks) - Resend email webhook handling
- [chargebee-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/chargebee-webhooks) - Chargebee billing webhook handling
- [clerk-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/clerk-webhooks) - Clerk auth webhook handling
- [openai-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/openai-webhooks) - OpenAI webhook handling
- [paddle-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/paddle-webhooks) - Paddle billing webhook handling
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Handler sequence, idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/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](https://github.com/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).
© hookdeck · MIT · hookdeck/webhook-skills