Leaper Central de Ajuda
Desenvolvedores Entrar

Eventos Disponíveis

Conheça os eventos que podem disparar webhooks.

Cinco 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 — Formulário do site — Um formulário da Leaper instalado no seu site foi enviado, seja por um contato novo ou por alguém que já estava na sua base.
  • lead_ads_submission — Formulário do Meta — Um formulário do Lead Ads (o formulário instantâneo do Facebook e do Instagram) foi enviado, seja por um contato novo ou por alguém que já estava na sua base.

Eventos que se sobrepõem

Eventos de formulário: o bloco status é contexto

Em três dos cinco eventos o bloco 'status' descreve a transição que acabou de acontecer. Nos dois 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' (formulários do site) e o bloco 'leadAdsSubmissions' (Lead Ads) trazem todos os envios daquele lead, do mais recente para o mais antigo; no evento correspondente, 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 número do WhatsApp conectado), lead (dados de contato e origem), status (etapa atual e anterior, quando houver), tracking (atribuição: campanha, UTMs, dispositivo, click IDs, página), formSubmissions (formulários do site enviados) e leadAdsSubmissions (formulários do Lead Ads enviados); as duas listas vêm vazias 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, form_submission ou lead_ads_submission. Permite rotear sem abrir o corpo.
  • X-Webhook-Signature — sha256= seguido do HMAC-SHA256 do corpo, em hexadecimal, usando o secret do webhook.