Webhooks
Habilite integrações externas recebendo eventos de webhook.
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 eventos atualmente compatíveis incluem:
Configuração
Os webhooks podem ser criados, desativados e excluídos na página de configurações gerais. Para usuários em Espaços de trabalho, somente os administradores do espaço de trabalho podem configurar os webhooks do espaço de trabalho.

Após a criação, o webhook pode ser selecionado para monitorar eventos nas configurações de produtos, como a plataforma Agents.
Os eventos flows_generation e flows_template_run são ativados pela mesma assinatura: em Selecione os eventos a serem monitorados, marque Geração ou execução de modelo da API de Imagem e Vídeo concluída, ou envie o evento flows para Atualizar webhook do espaço de trabalho. Uma geração ou execução envia seu evento somente 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 nunca tiver sido entregue com sucesso. Webhooks desativados automaticamente precisam ser reativados na página de configurações. Webhooks podem ser excluídos se não estiverem em uso por nenhum produto.
Tentativas
As tentativas de webhook podem ser ativadas por webhook para tentar automaticamente a entrega novamente quando uma solicitação falhar. As tentativas ficam desativadas por padrão. Ative as tentativas ao criar ou atualizar um webhook pela API ou nas configurações do webhook.
Há suporte para tentativas nos webhooks pós-chamada
do ElevenAgents, incluindo eventos de
transcrição (post_call_transcription), áudio (post_call_audio) e falha na iniciação
da chamada (call_initiation_failure).
Cronograma 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 picos simultâneos de solicitações.
Erros que permitem nova tentativa
Nem todas as falhas acionam uma nova tentativa. Somente as seguintes falhas permitem nova tentativa:
- Códigos de status
5xx(erros de servidor, como 500, 502, 503, 504). 429(Solicitações demais).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, 404) não geram nova tentativa, pois normalmente 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 enfileiradas, tarefas adicionais serão descartadas até que as tentativas existentes sejam processadas. Isso evita que um único webhook configurado incorretamente consuma recursos excessivos.
Os webhooks de áudio têm dois limites adicionais. Uma carga de áudio maior que 50 MiB é entregue uma vez e não recebe nova tentativa, e o total de novas tentativas de áudio enfileiradas para um único webhook não pode exceder 400 MiB.
Comportamento de desativação automática
O sistema monitora falhas consecutivas de entrega para cada webhook. Um webhook é automaticamente desativado quando ambas as 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 espaço de trabalho recebem uma notificação por e-mail. O webhook deve ser reativado manualmente na página de configurações antes de retomar as entregas.
Integração
Para integrar webhooks, crie um manipulador de endpoint para receber dados de eventos de webhook como solicitações POST. Após validar a assinatura, o manipulador deve retornar HTTP 200 rapidamente para indicar o recebimento bem-sucedido. Falhas repetidas ao retornar uma resposta de sucesso podem fazer com que o webhook seja desativado automaticamente.
A carga da nova tentativa é idêntica à tentativa de entrega original. Os consumidores de webhook não conseguem distinguir entre uma entrega inicial e uma nova tentativa apenas pela carga; portanto, desenvolva seu manipulador para ser idempotente — processar o mesmo evento várias vezes deve gerar 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
Webhooks de remoção de voz
Um espaço de trabalho recebe esses eventos para uma voz compartilhada da Voice Library que adicionou, quando o proprietário da voz ou a ElevenLabs a remove da Voice Library.
Aviso de remoção (voice_removal_notice)
A voz tem um período de aviso. Ela permanece utilizável até future_removal_timestamp.
Nenhum outro evento é enviado quando o período de aviso termina.
Estrutura do objeto de dados
Aviso de remoção cancelado (voice_removal_notice_withdrawn)
A voz não está mais programada para remoção e permanece utilizável.
Estrutura do objeto de dados
Voz removida (voice_removed)
A voz foi removida sem período de aviso e não pode mais ser usada.
Estrutura do objeto de dados
Vozes sugeridas
Cada item em suggested_voices é uma matriz de dois itens: a URL de compartilhamento da Voice Library da voz e, em seguida, o nome da voz. A lista pode estar vazia.
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.
Python
JavaScript
Exemplo de manipulador de webhook usando FastAPI: