Eventos Disponíveis
Conheça os eventos que podem disparar webhooks.
Quatro eventos podem disparar webhooks. O código ao lado de cada nome é o que chega no campo 'event' do pacote — é por ele que o seu sistema decide o que fazer. A estrutura do payload é sempre a mesma; o que muda é o valor de 'event' e quais blocos vêm preenchidos.
Eventos
- new_lead — Novo Lead — Um lead entrou na sua base, por qualquer canal. É o primeiro status que ele recebe.
- status_change — Mudança de Status — Um lead mudou de etapa no funil. Vale para qualquer transição, inclusive as finais.
- lead_converted — Lead Convertido — Um lead chegou à etapa de conversão (END_WON). É a transição de venda ganha, isolada das demais — permite tratar conversões sem inspecionar códigos de etapa.
- form_submission — Submissão de Formulário — Um formulário foi enviado, seja por um contato novo ou por alguém que já estava na sua base.
Eventos que se sobrepõem
Submissão de Formulário: o bloco status é contexto
Em três dos quatro eventos o bloco 'status' descreve a transição que acabou de acontecer. Em Submissão de Formulário ele é só contexto: diz em que etapa o lead está agora, com 'previous' nulo e 'changed_at' possivelmente de dias atrás. É proposital — a etapa atual é o que decide o que fazer com uma resubmissão. O bloco 'formSubmissions' traz todos os envios daquele lead, do mais recente para o mais antigo; o primeiro item é sempre o que gerou a chamada.
Estrutura do payload
POST com Content-Type: application/json. O corpo contém: event (tipo do evento), timestamp (UTC), company (id e whatsapp), lead (dados de contato e origem), status (etapa atual e anterior, quando houver), tracking (atribuição: campanha, UTMs, dispositivo, click IDs, página) e formSubmissions (formulários enviados; lista vazia quando não houver). Qualquer campo pode vir null quando o dado não existe — trate ausência como normal. O corpo de cada evento, campo a campo, está na referência dos webhooks.
Headers enviados
- Content-Type — application/json
- X-Webhook-Event — Nome do evento: new_lead, status_change, lead_converted ou form_submission. Permite rotear sem abrir o corpo.
- X-Webhook-Signature — sha256= seguido do HMAC-SHA256 do corpo, em hexadecimal, usando o secret do webhook.