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.
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_INTERACTIONpode chegar depois doAI_RESPONSEda 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 emevent. 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:
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 emevent e os campos do lead “achatados”.
LEAD_KANBAN_UPDATED
LEAD_TAG_ADDED e LEAD_TAG_REMOVED
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 UnavailableouECONNABORTED: timeout of 20000ms exceeded); - ninguém é avisado por e-mail ou push. O selo é o único aviso.
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.
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.Diferenças por conexão
Pelo MCP
Blocowebhooks do template.
- Item identificado por
name. Mudar o nome cria outro webhook. - Webhook criado sem
urlnasce desligado e sem endereço; só liga com endereço.urlvazia 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_templatesó comostatus: "INACTIVE". Antes de religar comstatus: "ACTIVE", pergunte se o endpoint foi consertado; religar um endpoint quebrado faz ele cair de novo em 10 falhas. get_templatetraz 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_ADDEDeLEAD_TAG_REMOVEDcontinuam 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_RESPONSEtraz texto; os outros eventos de conversa trazem objetos. Um parser único paramessage.messagesquebra.ai_response_block: truenão quer dizer IA parada agora. Compareai_response_block_untilcom o horário atual.- Tags e colunas chegam como ids no formato 1. Traduza com
GET /tagseGET /kanban, ou use os eventos de Kanban e tags, que trazem nomes. - Campo legado do motor antigo. Se o bloco
llm_attendanttiver o campowebhookspreenchido, os eventosLEAD_CREATED,LEAD_INTERACTIONeAI_RESPONSEvã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
Dá para receber os eventos de novo depois de uma falha?
Dá para receber os eventos de novo depois de uma falha?
Não. A Zatten não guarda nem reenvia eventos. Recupere o estado pela API (
GET /leads/{numero} e o histórico de mensagens).Dá para mandar um header de autenticação?
Dá para mandar um header de autenticação?
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.
Como saber de qual cliente final veio o evento?
Como saber de qual cliente final veio o evento?
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.Posso usar o webhook para responder ao lead?
Posso usar o webhook para responder ao lead?
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
- Webhooks de saída: referência
- Webhook por inatividade
- API: leads e catálogos
- Trigger Flow: para reagir a eventos com condição e várias ações.
- Meta: anúncios Click-to-WhatsApp.
- Termos para buscar: “webhook idempotency”, “webhook receiver best practices”, “respond 200 then process async”, “ctwa_clid”.