Skip to main content
O webhook de eventos faz a Zatten mandar um POST com JSON para um endereço seu na hora em que algo acontece com um lead: lead criado, mensagem recebida, resposta do agente, mudança de coluna, tag, erro. Serve para alimentar um CRM externo, uma planilha, um painel ou uma automação no n8n, Make ou Zapier.
Não há nova tentativa nem assinatura. Se o seu endpoint estiver fora do ar, o evento se perde. Depois de 10 falhas seguidas, o webhook é desligado sozinho. Leia Como montar o endpoint que recebe antes de ligar em produção.

Onde fica no painel

Automações → Automações nativas → criar → Webhook. Um projeto pode ter vários webhooks, cada um com seu endereço e seus eventos.

Como configurar

Todas as chaves começam desligadas. A chave ligada / desligada fica na lista de automações.

Os eventos

“Saiu” quer dizer: na conexão oficial, a Meta confirmou a entrega; na não oficial, o status de enviado chegou. Por isso CRM_INTERACTION e API_KEY_INTERACTION chegam alguns segundos depois do envio. Um template enviado pelo CRM ou pela API gera os dois: WA_TEMPLATE no envio e CRM_INTERACTION ou API_KEY_INTERACTION na entrega. Não geram evento: ações em massa no CRM, encerrar o atendimento (o lead volta para a primeira coluna sem LEAD_KANBAN_UPDATED), importação de CSV e as mensagens do reengajamento, do transbordo e da resposta para mensagens não visíveis.

Como a requisição chega

  • Método e corpo: POST, Content-Type: application/json.
  • Sem assinatura: não há header de assinatura nem segredo. Quem conhece a URL pode mandar dados para ela. Veja como se proteger abaixo.
  • Sem nova tentativa: cada evento é enviado uma vez. Falhou, perdeu.
  • Tempo limite: 20 segundos para os eventos de lead, conversas e erros; 10 segundos para Kanban e tags.
  • Sucesso é qualquer resposta 2xx ou 3xx. O corpo da resposta é ignorado.
  • Sem garantia de ordem: eventos saem de lugares diferentes e podem chegar fora de ordem. LEAD_INTERACTION pode chegar depois do AI_RESPONSE da mesma conversa, em casos de lentidão.
  • Sem id de evento: use os campos indicados em idempotência.
  • Dois formatos: os eventos de lead, conversas e erros trazem o tipo em type; os de Kanban e tags trazem em event. Leia os dois campos para saber qual chegou.

Formato 1: lead, conversas e erros

Todos estes eventos têm a mesma forma: type, lead, attendant, message (quando há mensagem ou erro) e timestamp. Exemplo de LEAD_INTERACTION:
O timestamp está em UTC (o Z no fim é verdadeiro): 14:03:22.000Z são 11:03:22 em Brasília. Neste formato a precisão é de segundos; os milissegundos saem sempre .000.

Campos

Campo sem valor não vem. Em vez de null, campos vazios do lead (last_interaction, tags, column_id, notes, assigned_to_user…) simplesmente não aparecem no JSON. Trate ausência como vazio.

message em cada evento

LEAD_CREATED e adsData

adsData só vem quando o lead nasceu de uma mensagem de anúncio Click-to-WhatsApp na conexão oficial: Lead orgânico, lead criado por template e qualquer lead da conexão não oficial chegam sem adsData. Os dados completos do anúncio também alimentam as conversões para o Meta Ads.

ERROR

code é um texto livre de diagnóstico, por exemplo ERROR_META_UNDELIVERABLE - 131026, ERROR_META_UNAVAILABLE - 131060 ou ERROR_UNSUPPORTED_MEDIA. Pode vir com espaço no começo. Use para alertar e registrar; não monte lógica que dependa do formato exato.

Formato 2: Kanban e tags

Estes eventos têm o tipo em event e os campos do lead “achatados”.

LEAD_KANBAN_UPDATED

LEAD_TAG_ADDED e LEAD_TAG_REMOVED

Aqui current_tags traz id, nome e descrição (no formato 1, lead.tags traz só ids). lead_metadata usa o slug da propriedade em prop_name. Os campos vazios vêm como null.

Desligamento automático após 10 falhas

Um webhook que falha 10 vezes seguidas é desligado sozinho. Um sucesso no meio zera a contagem. A sequência também é esquecida 7 dias depois da última falha. Conta como falha: resposta 4xx (inclusive 401, 403, 404, 410), 5xx, 429, tempo limite estourado, erro de DNS, conexão recusada ou interrompida. Não conta: resposta 2xx ou 3xx (zera a contagem). Quando desliga:
  • o webhook fica desligado, com o selo vermelho Desligado automaticamente ao lado da chave;
  • passando o mouse no selo: quantas falhas, quando desligou e o último erro (por exemplo HTTP 503 Service Unavailable ou ECONNABORTED: timeout of 20000ms exceeded);
  • ninguém é avisado por e-mail ou push. O selo é o único aviso.
Vale para os eventos de lead, conversas e erros e para o webhook por inatividade. Os eventos de Kanban e tags não contam falhas.

Como religar

1

Descubra o que falhou

Leia o último erro no selo. 404 ou 410: o endereço mudou. 401 ou 403: a autenticação do seu endpoint mudou. Tempo limite: o endpoint está lento demais (veja abaixo).
2

Conserte o endpoint ou a URL

Se a URL mudou, edite o webhook e salve a nova.
3

Ligue a chave

Na lista, ligue a chave do webhook. O painel pergunta Religar webhook? e lembra que, se o destino ainda estiver com problema, ele será desligado de novo. Confirme em Religar. A contagem de falhas recomeça do zero.
Os eventos do período em que o webhook ficou desligado não são reenviados. Para recuperar, consulte a API (GET /leads/{numero}, histórico de mensagens).

Como montar o endpoint que recebe

1

Responda 2xx rápido e processe depois

Grave o corpo numa fila (ou numa tabela) e responda 200 imediatamente. Não chame outra API, não escreva em planilha, não rode IA antes de responder. Mire em menos de 2 segundos: o limite é 20 segundos (10 para Kanban e tags), e cada estouro conta para o desligamento automático.
2

Responda 2xx mesmo para o que você ignora

Evento que você não usa, ou payload que não entendeu: responda 200 e descarte. Um 400 ou 422 conta como falha e, repetido 10 vezes, desliga o webhook inteiro.
3

Torne o processamento idempotente

Não há id de evento e, em casos raros, o mesmo fato pode chegar duas vezes. Monte uma chave e ignore repetidos:
4

Não dependa da ordem

Os eventos podem chegar fora de ordem. Guarde o timestamp e não deixe um evento mais antigo sobrescrever um mais novo. Quando precisar do estado atual de verdade (coluna, tags, responsável), consulte a API: GET /leads/{numero}.
5

Proteja o endereço

Sem assinatura, a URL é o segredo. Use https, coloque um token longo e aleatório no caminho ou na query (https://seu-sistema.com/zatten/hook/7f3a…) e rejeite chamadas sem ele. Confira se attendant.id (ou attendant_id) é um projeto seu. Para ações sensíveis (cobrar, cancelar), não confie só no payload: confirme pela API.
Exemplo mínimo em Node.js (Express):
No processamento, calcule a chave de idempotência da tabela acima e ignore o que já foi visto.

Diferenças por conexão

Pelo MCP

Bloco webhooks do template.
  • Item identificado por name. Mudar o nome cria outro webhook.
  • Webhook criado sem url nasce desligado e sem endereço; só liga com endereço. url vazia não grava por cima da atual.
  • Os eventos são as chaves lead_created, conversations, kanban, tags, errors.
  • O motivo do desligamento não viaja. Um webhook desligado automaticamente aparece em get_template só como status: "INACTIVE". Antes de religar com status: "ACTIVE", pergunte se o endpoint foi consertado; religar um endpoint quebrado faz ele cair de novo em 10 falhas.
  • get_template traz a URL preenchida. Não mostre a URL inteira ao cliente se ela tiver token.

Armadilhas

  • timestamp é UTC, não Brasília. Quem grava o valor numa planilha como se fosse hora local vê tudo 3 horas adiantado. Converta antes de mostrar.
  • Desligar o webhook não para Kanban e tags. Os eventos LEAD_KANBAN_UPDATED, LEAD_TAG_ADDED e LEAD_TAG_REMOVED continuam saindo para webhooks desligados, inclusive os desligados automaticamente. Para parar, desmarque Kanban e Tags ou exclua o webhook.
  • Resposta lenta desliga o webhook. Processar tudo antes de responder (planilha, IA, outra API) estoura os 20 segundos em horário de pico, e 10 estouros seguidos desligam.
  • Responder 4xx para evento desconhecido desliga o webhook. Responda 2xx e ignore.
  • AI_RESPONSE traz texto; os outros eventos de conversa trazem objetos. Um parser único para message.messages quebra.
  • ai_response_block: true não quer dizer IA parada agora. Compare ai_response_block_until com o horário atual.
  • Tags e colunas chegam como ids no formato 1. Traduza com GET /tags e GET /kanban, ou use os eventos de Kanban e tags, que trazem nomes.
  • Campo legado do motor antigo. Se o bloco llm_attendant tiver o campo webhooks preenchido, os eventos LEAD_CREATED, LEAD_INTERACTION e AI_RESPONSE vão só para esse endereço, e não para os webhooks configurados aqui. Esvazie esse campo ao migrar; se não conseguir, peça ao suporte da Zatten pelo WhatsApp.
  • Mudança em massa não gera evento. Mover ou etiquetar vários leads de uma vez pelo CRM não envia nada.

Perguntas frequentes

Não. A Zatten não guarda nem reenvia eventos. Recupere o estado pela API (GET /leads/{numero} e o histórico de mensagens).
Não no webhook de eventos: ele não tem campo de headers. Use um token na URL. As ações personalizadas e as tools HTTP do agente aceitam headers.
Pelo attendant.id (formato 1) ou attendant_id (formato 2), que é o id do projeto. Se você usa um endpoint para vários projetos, mapeie esse id para o cliente.
Pode, chamando a API de mensagens a partir do seu sistema. Lembre que o agente também vai responder, a não ser que você pause a IA do lead pela API.

Para saber mais