Webhook | ElevenLabs Documentation

概要

ElevenLabs内の特定のイベントではWebhookをトリガーするよう設定でき、外部アプリケーションやシステムはイベント発生時に受信・処理できます。現在サポートされているイベントタイプは次のとおりです。

イベントタイプ	説明
`post_call_transcription`	Agents Platformの通話が終了し、分析が完了した
`voice_removal_notice`	共有音声の削除が予定されている
`voice_removal_notice_withdrawn`	共有音声の削除予定が取り消された
`voice_removed`	共有音声が削除され、使用できなくなった

設定

Webhookは一般設定ページから作成、無効化、削除できます。ワークスペース内のユーザーの場合、ワークスペースのWebhookを設定できるのはワークスペース管理者のみです。

作成後、Agents Platformなどのプロダクト設定で、Webhookがイベントをリッスンするよう選択できます。

Webhookはいつでも一般設定ページから無効化できます。10回以上連続で失敗し、最後の配信成功から7日を超えている、または一度も正常に配信されていないWebhookは自動的に無効化されます。自動的に無効化されたWebhookは、設定ページで再度有効にする必要があります。どのプロダクトでも使用されていないWebhookは削除できます。

再試行

Webhookごとに再試行を有効にすると、リクエストが失敗した際に配信を自動的に再試行できます。再試行はデフォルトで無効です。APIまたはWebhook設定でWebhookを作成・更新する際に有効にしてください。

現在、再試行がサポートされているのはpost_call_transcriptionWebhookのみです。

再試行スケジュール

配信試行が再試行可能なエラーで失敗すると、システムは試行間の遅延を増やしながら最大5回再試行します。

試行	遅延
1	即時
2	30秒
3	2分
4	8分
5	30分

負荷を分散し、サンダリングハード問題を回避するため、各再試行には小さなランダムジッター（遅延の最大10%）が追加されます。

再試行可能なエラー

すべての失敗で再試行が行われるわけではありません。再試行可能と見なされるHTTPステータスコードは次のみです。

5xxステータスコード（500、502、503、504などのサーバーエラー）。
429（リクエストが多すぎます）。
408（リクエストタイムアウト）。

4xx範囲のリクエストエラー（400、401、403、404など）は、通常は手動での修正が必要な設定上の問題を示すため、再試行されません。

Webhookごとのキュー上限

各Webhookの保留中の再試行ジョブは100件までです。Webhookに100件を超える再試行がキューイングされると、既存の再試行が処理されるまで追加ジョブは破棄されます。これにより、設定ミスのある単一のWebhookが過剰なリソースを消費することを防ぎます。

自動無効化の動作

システムはWebhookごとに連続した配信失敗を追跡します。次の両方の条件を満たすと、Webhookは自動的に無効になります。

連続して10回以上の配信失敗が発生している。
Webhookが一度も正常に配信されていない、または最後の配信成功から7日を超えている。

Webhookが自動的に無効になると、ワークスペース管理者にメール通知が届きます。配信を再開するには、設定ページでWebhookを手動で再有効化する必要があります。

インテグレーション

Webhookとインテグレーションするには、WebhookイベントデータをPOSTリクエストとして受信するエンドポイントハンドラーを作成します。署名を検証した後、正常に受信したことを示すため、ハンドラーは速やかにHTTP 200を返す必要があります。成功レスポンスを返せない状態が繰り返されると、Webhookが自動的に無効になる場合があります。

再試行のペイロードは、元の配信試行と同一です。Webhookコンシューマーはペイロードだけでは初回配信と再試行を区別できないため、ハンドラーは冪等に設計してください。同じイベントを複数回処理しても、同じ結果になる必要があります。必要に応じて、event_timestampとイベント固有の識別子（conversation_idなど）を使用してイベントの重複を排除してください。

トップレベルフィールド

フィールド	タイプ	説明
`type`	string	イベントのタイプ
`data`	object	イベントのデータ
`event_timestamp`	string	イベントの発生日時

Webhookペイロードの例

{
  "type": "post_call_transcription",
  "event_timestamp": 1739537297,
  "data": {
    "agent_id": "xyz",
    "conversation_id": "abc",
    "status": "done",
    "transcript": [
      {
        "role": "agent",
        "message": "Hey there angelo. How are you?",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 0,
        "conversation_turn_metrics": null
      },
      {
        "role": "user",
        "message": "Hey, can you tell me, like, a fun fact about 11 Labs?",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 2,
        "conversation_turn_metrics": null
      },
      {
        "role": "agent",
        "message": "I do not have access to fun facts about Eleven Labs. However, I can share some general information about the company. Eleven Labs is an AI voice technology platform that specializes in voice cloning and text-to-speech...",
        "tool_calls": null,
        "tool_results": null,
        "feedback": null,
        "time_in_call_secs": 9,
        "conversation_turn_metrics": {
          "convai_llm_service_ttfb": {
            "elapsed_time": 0.3704247010173276
          },
          "convai_llm_service_ttf_sentence": {
            "elapsed_time": 0.5551181449554861
          }
        }
      }
    ],
    "metadata": {
      "start_time_unix_secs": 1739537297,
      "call_duration_secs": 22,
      "cost": 296,
      "deletion_settings": {
        "deletion_time_unix_secs": 1802609320,
        "deleted_logs_at_time_unix_secs": null,
        "deleted_audio_at_time_unix_secs": null,
        "deleted_transcript_at_time_unix_secs": null,
        "delete_transcript_and_pii": true,
        "delete_audio": true
      },
      "feedback": {
        "overall_score": null,
        "likes": 0,
        "dislikes": 0
      },
      "authorization_method": "authorization_header",
      "charging": {
        "dev_discount": true
      },
      "termination_reason": ""
    },
    "analysis": {
      "evaluation_criteria_results": {},
      "data_collection_results": {},
      "call_successful": "success",
      "transcript_summary": "The conversation begins with the agent asking how Angelo is, but Angelo redirects the conversation by requesting a fun fact about 11 Labs. The agent acknowledges they don't have specific fun facts about Eleven Labs but offers to provide general information about the company. They briefly describe Eleven Labs as an AI voice technology platform specializing in voice cloning and text-to-speech technology. The conversation is brief and informational, with the agent adapting to the user's request despite not having the exact information asked for."
    },
    "conversation_initiation_client_data": {
      "conversation_config_override": {
        "agent": {
          "prompt": null,
          "first_message": null,
          "language": "en"
        },
        "tts": {
          "voice_id": null
        }
      },
      "custom_llm_extra_body": {},
      "dynamic_variables": {
        "user_name": "angelo"
      }
    }
  }
}

認証

受信側は、すべての受信Webhookを検証することが重要です。Webhookは現在、HMAC署名による認証に対応しています。HMAC認証は次の手順で設定します。

Webhookの作成時に生成された共有シークレットを安全に保存する
SDKを使用してエンドポイントでElevenLabs-Signatureヘッダーを検証する

JavaScript SDKではconstructEventを、Python SDKでは**rawBody、sig_header、secret**を指定するconstruct_eventを利用できます（Pythonではpayload／signatureという名前ではありません）。どちらも署名の検証、タイムスタンプの検証、JSONペイロードの解析を行います。

Python

JavaScript

FastAPIを使用したWebhookハンドラーの例：

from dotenv import load_dotenv
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from elevenlabs.client import ElevenLabs
from elevenlabs.errors import BadRequestError
import os
load_dotenv()
app = FastAPI()
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET")
@app.post("/webhook")
async def receive_message(request: Request):
    payload = await request.body()
    signature = request.headers.get("elevenlabs-signature")
    try:
        event = elevenlabs.webhooks.construct_event(
            rawBody=payload.decode("utf-8"),
            sig_header=signature,
            secret=WEBHOOK_SECRET,
        )
    except BadRequestError as e:
        return JSONResponse(content={"error": "Invalid signature"}, status_code=401)
    # construct_event returns a dict (parsed JSON), not an object with attributes
    if event.get("type") == "post_call_transcription":
        print(f"Received transcription: {event.get('data')}")
    return {"status": "received"}