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。如果 webhook 连续失败 10 次或以上，且距离上次成功投递已超过 7 天或从未成功投递，系统会自动将其禁用。自动禁用的 webhook 需要在设置页面重新启用。如果没有任何产品在使用，也可以删除 webhook。

重试

可为每个 webhook 启用重试，以便请求失败时自动重新尝试投递。默认关闭重试。可通过 API 或 webhook 设置，在创建或更新 webhook 时启用重试。

目前仅 post_call_transcription webhook 支持重试。

重试计划

当投递尝试因可重试错误而失败时，系统最多重试 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，请创建端点处理程序，以 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 提供 construct_event，并使用 rawBody、sig_header 和 secret（在 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"}