elevenlabs-webhooks

ElevenLabs Webhook

このスキルを使用する場面

• ElevenLabs の webhook ハンドラーを設定する
• 署名検証の失敗をデバッグする
• ElevenLabs のイベントタイプとペイロードを理解する
• 通話の文字起こしイベントを処理する
• 音声削除の通知を処理する

重要なコード

署名検証（SDK — 推奨）

ElevenLabs は、webhook の検証とイベントの構築に公式の @elevenlabs/elevenlabs-js SDK を使用することを推奨しています。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 webhook の概要と、よく使用されるイベントタイプ
• セットアップ - ElevenLabs ダッシュボードで webhook を設定し、署名シークレットを取得する方法
• 検証 - 署名検証の詳細と注意点
• 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 の E コマース 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 呼び出し（テキスト読み上げ、文字起こし、エージェント）については、公式の ElevenLabs Skills をご覧ください。このスキルは逆方向、つまり ElevenLabs から Webhook を受信する処理を扱います。

SDK に関する注意： JavaScript では必ず @elevenlabs/elevenlabs-js を使用してください。npm install elevenlabs は使用しないでください（これは古い v1.x パッケージです）。