Webhooks | ElevenLabs Documentation

概要

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

イベントタイプ	説明
`post_call_transcription`	Agents Platformの通話が終了し、分析が完了した
`voice_removal_notice`	共有音声の削除が予定されている
`voice_removal_notice_withdrawn`	共有音声の削除予定が取り消された
`voice_removed`	共有音声が削除され、使用できなくなった
`flows_generation`	画像＆ビデオの生成が完了または失敗した
`flows_template_run`	テンプレート実行が完了または失敗した

設定

webhookは、一般設定ページから作成、無効化、削除できます。ワークスペース内のユーザーについては、ワークスペース管理者のみがワークスペースのwebhookを設定できます。

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

flows_generationイベントとflows_template_runイベントは、どちらも1つのサブスクリプションで有効になります。リッスンするイベントを選択で画像＆ビデオAPIの生成またはテンプレート実行の完了にチェックを入れるか、ワークスペースwebhookを更新にflowsイベントを渡します。生成または実行は、作成リクエストにwebhookフィールドが含まれる場合にのみイベントを送信します。

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

リトライ

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

リトライは、文字起こし（post_call_transcription）、オーディオ（post_call_audio）、通話開始失敗（call_initiation_failure）イベントを含む、ElevenAgentsの通話後webhookでサポートされています。

リトライスケジュール

再試行可能なエラーで配信試行が失敗した場合、試行間の遅延を増やしながら最大5回再試行します。

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

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

再試行可能なエラー

すべての失敗でリトライがトリガーされるわけではありません。再試行可能と見なされる失敗は以下のみです。

5xxステータスコード（500、502、503、504などのサーバーエラー）。
429（リクエスト過多）。
408（リクエストタイムアウト）。
接続エラーおよびリクエストタイムアウト。

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

webhookごとのキュー上限

各webhookは、保留中のリトライジョブが100件までに制限されます。webhookに100件を超えるリトライがキューに蓄積された場合、既存のリトライが処理されるまで追加ジョブは破棄されます。これにより、設定ミスのある1つのwebhookが過剰なリソースを消費することを防ぎます。

オーディオwebhookには追加で2つの制限があります。50MiBを超えるオーディオペイロードは1回のみ配信され、リトライされません。また、1つのwebhookでキューに入れられるオーディオのリトライは、合計400MiBを超えることはできません。

自動無効化の動作

システムはwebhookごとに連続した配信失敗を追跡します。以下の両方の条件を満たすと、webhookは自動的に無効化されます。

10回以上連続して配信に失敗した。
webhookの配信が一度も成功していない、または最後の配信成功から7日以上経過している。

webhookが自動的に無効化されると、ワークスペース管理者にメール通知が送信されます。配信を再開するには、設定ページから手動でwebhookを再度有効にする必要があります。

インテグレーション

webhookとインテグレーションするには、POSTリクエストとしてwebhookイベントデータを受信するエンドポイントハンドラーを作成します。署名を検証した後、正常に受信したことを示すため、ハンドラーは速やかに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"}