Webhooks

Visão geral

Determinados eventos na ElevenLabs podem ser configurados para acionar webhooks, permitindo que aplicações e sistemas externos recebam e processem esses eventos à medida que ocorrem. Os tipos de evento aceitos atualmente incluem:

Configuração

Os webhooks podem ser criados, desativados e excluídos na página de configurações gerais. Para usuários em Workspaces, somente os administradores do workspace podem configurar os webhooks dele.

Após a criação, o webhook pode ser selecionado para receber eventos nas configurações de produtos, como a Agents Platform.

Os eventos flows_generation e flows_template_run são habilitados por uma única inscrição: em Select events to listen to, marque Image & Video API generation or template run completed, ou envie o evento flows para Atualizar webhook do workspace. Uma geração ou execução só envia seu evento quando a solicitação de criação inclui um campo webhook.

Os webhooks podem ser desativados a qualquer momento na página de configurações gerais. Webhooks que falham repetidamente são desativados automaticamente se houver 10 ou mais falhas consecutivas e a última entrega bem-sucedida tiver ocorrido há mais de 7 dias, ou se nunca tiver havido uma entrega bem-sucedida. Webhooks desativados automaticamente precisam ser reativados na página de configurações. Eles podem ser excluídos se não estiverem em uso por nenhum produto.

Tentativas

As tentativas de webhook podem ser habilitadas por webhook para tentar novamente a entrega automaticamente quando uma solicitação falha. Elas ficam desativadas por padrão. Habilite as tentativas ao criar ou atualizar um webhook pela API ou nas configurações do webhook.

Programação de tentativas

Quando uma tentativa de entrega falha com um erro que permite nova tentativa, o sistema tenta novamente até 5 vezes, com intervalos crescentes entre as tentativas:

Uma pequena variação aleatória (de até 10% do intervalo) é adicionada a cada nova tentativa para distribuir a carga e evitar problemas de excesso simultâneo de solicitações.

Erros que permitem nova tentativa

Nem todas as falhas acionam uma nova tentativa. Apenas as seguintes falhas são consideradas recuperáveis:

• Códigos de status 5xx (erros de servidor, como 500, 502, 503 e 504).
• 429 (Muitas solicitações).
• 408 (Tempo limite da solicitação).
• Erros de conexão e tempos limite de solicitação.

Erros de solicitação na faixa 4xx (como 400, 401, 403 e 404) não recebem novas tentativas, pois geralmente indicam um problema de configuração que exige correção manual.

Limites de fila por webhook

Cada webhook é limitado a 100 tarefas de nova tentativa pendentes. Se um webhook acumular mais de 100 tentativas na fila, as tarefas adicionais serão descartadas até que as tentativas existentes sejam processadas. Isso evita que um único webhook mal configurado consuma recursos excessivos.

Webhooks de áudio têm dois limites adicionais. Uma carga de áudio maior que 50 MiB é entregue uma vez e não recebe novas tentativas, e o total de tentativas de áudio em fila para um único webhook não pode exceder 400 MiB.

Comportamento de desativação automática

O sistema rastreia falhas consecutivas de entrega para cada webhook. Um webhook é desativado automaticamente quando as duas condições a seguir são atendidas:

• Ocorreram 10 ou mais falhas consecutivas de entrega.
• O webhook nunca foi entregue com sucesso ou a última entrega bem-sucedida ocorreu há mais de 7 dias.

Quando um webhook é desativado automaticamente, os administradores do workspace recebem uma notificação por e-mail. O webhook deve ser reativado manualmente na página de configurações antes de voltar a entregar eventos.

Integração

Para integrar com webhooks, crie um manipulador de endpoint para receber os dados de eventos de webhook como solicitações POST. Depois de validar a assinatura, o manipulador deve retornar HTTP 200 rapidamente para indicar o recebimento bem-sucedido. Falhas repetidas em retornar uma resposta de sucesso podem fazer com que o webhook seja desativado automaticamente.

A carga de uma nova tentativa é idêntica à da tentativa de entrega original. Os consumidores de webhooks não podem distinguir uma entrega inicial de uma nova tentativa apenas pela carga, então crie seu manipulador para ser idempotente — processar o mesmo evento várias vezes deve produzir o mesmo resultado. Use event_timestamp e identificadores específicos do evento (como conversation_id) para eliminar eventos duplicados, se necessário.

Campos de nível superior

Exemplo de carga de 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"
      }
    }
  }
}

Autenticação

É importante que o listener valide todos os webhooks recebidos. Atualmente, os webhooks oferecem suporte à autenticação por assinaturas HMAC. Configure a autenticação HMAC:

• Armazenando com segurança o segredo compartilhado gerado na criação do webhook
• Verificando o cabeçalho ElevenLabs-Signature no seu endpoint usando o SDK

O SDK JavaScript disponibiliza constructEvent; o SDK Python disponibiliza construct_event com rawBody, sig_header e secret (em Python, eles não se chamam payload / signature). Ambos verificam a assinatura, validam o carimbo de data e hora e analisam o payload JSON.

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"}