Visão geral
Você cadastra um endereço de destino, escolhe quais eventos quer receber e usa a chave de assinatura para confirmar que a chamada veio mesmo da Leaper. Daí em diante o seu sistema é avisado sozinho — a cada lead novo, a cada mudança de etapa.
Toda entrega é um POST com corpo JSON e a mesma estrutura de blocos, qualquer que seja o evento. O que muda é o valor de event e quais blocos vêm preenchidos.
Quando a entrega acontece
O evento entra numa fila e a entrega acontece logo em seguida, não no exato instante do acontecimento. Na prática isso significa duas coisas:
- O corpo é montado na hora do envio. Se o lead foi enriquecido nesse intervalo — o nome chegou depois, os dados de campanha foram resolvidos — você já recebe a versão atual.
- O bloco status descreve a transição que gerou o evento, mesmo que o lead tenha mudado de etapa de novo nesse meio tempo. Ele continua contando o que aconteceu.
Ativar seu webhook
A configuração fica no painel, em Configurações → Webhooks. São três coisas: o endereço, os eventos e a chave de assinatura que geramos para você.
O endereço de destino
Precisa aceitar POST com corpo JSON, estar acessível pela internet e usar HTTPS. Endereços internos — localhost, IPs de rede privada e semelhantes — são recusados, inclusive quando aparecem no meio de um redirecionamento. Para os primeiros testes, serviços gratuitos como o Webhook.site já mostram os dados chegando.
Os eventos
Marque só o que o seu sistema vai tratar. Evento que você não usa gera chamada desnecessária e deixa o histórico mais difícil de ler quando precisar investigar algo. Os cinco disponíveis estão na referência.
A chave de assinatura
Cada webhook tem uma chave própria, gerada automaticamente. É com ela que o seu sistema confirma que a chamada veio da Leaper. Veja em Ver secret, copie e guarde num cofre de segredos ou numa variável de ambiente — evite deixá-la escrita no código. Ela continua disponível no painel, não é exibida uma única vez.
Cabeçalhos extras, se precisar
Se o seu endpoint exige autenticação própria, dá para cadastrar cabeçalhos que acompanham toda chamada. Os três que a Leaper define — Content-Type, X-Webhook-Event e X-Webhook-Signature — não podem ser sobrescritos.
Enviar um teste
Na tela do webhook, Enviar teste manda na hora um exemplo de cada evento que você escolher para o endereço cadastrado e mostra o que o seu servidor respondeu: o código HTTP, o tempo e o começo da resposta. É o jeito mais rápido de conferir o endereço, a assinatura e os cabeçalhos de autenticação antes do primeiro lead de verdade.
- É o mesmo envio de verdade: mesma assinatura, mesmos cabeçalhos, mesmo tempo limite. Se o teste passa, as entregas reais também passam.
- Os dados são de exemplo. O lead é fictício, igual aos exemplos da referência. Só company.id e company.whatsapp_phone são os da sua empresa.
- Dá para reconhecer um teste: ele chega com o cabeçalho X-Webhook-Test: true e o campo "test": true no corpo. Use isso para não gravar testes no seu sistema de produção.
- Não entra no histórico de entregas e não tem nova tentativa: o resultado aparece só na tela.
- Endereço que só aceita GET: a Leaper envia sempre POST. Se o seu servidor responder 405, a tela avisa que o endereço não aceita POST — configure o endpoint para receber POST.
- Funciona para qualquer evento, mesmo os que o webhook não assina, e também com o webhook pausado. Dá para enviar um teste a cada 10 segundos por webhook.
Eventos que se sobrepõem
Alguns eventos descrevem o mesmo acontecimento sob ângulos diferentes, e assinar os dois faz o seu endpoint receber duas chamadas:
- Conversão. Um lead convertido também mudou de status. Com status_change e lead_converted marcados, chegam duas chamadas — uma de cada evento.
- Formulário de contato novo. Um envio feito por quem ainda não estava na base também cria o lead, então dispara form_submission e new_lead. Com formulário do Lead Ads é igual: lead_ads_submission e new_lead.
A sobreposição é intencional: ela deixa você tratar só a venda ganha sem olhar código de etapa. Se os dois eventos levam ao mesmo processamento no seu lado, assine apenas um.
Verificar a assinatura
Toda chamada vai assinada. Verificar a assinatura é o que garante que a requisição veio da Leaper e que ninguém alterou o conteúdo no caminho — sem isso, qualquer pessoa que descubra a URL do seu endpoint pode enviar dados falsos para ele.
| Cabeçalho | Conteúdo |
|---|---|
| Content-Type | application/json |
| X-Webhook-Event | Nome do evento. Permite rotear sem abrir o corpo |
| X-Webhook-Signature | sha256= seguido do HMAC-SHA256 do corpo, em hexadecimal, usando o secret do webhook |
Calcule o HMAC sobre os bytes exatos que chegaram, antes de qualquer conversão para objeto. Se você fizer JSON.parse e depois JSON.stringify de novo, a ordem das chaves e os espaços podem mudar e a assinatura nunca vai bater. Compare sempre com uma função de tempo constante, nunca com ==.
const crypto = require("crypto"); app.post( "/integracoes/leaper", express.raw({ type: "application/json" }), // mantém o corpo cru (req, res) => { const recebida = req.header("X-Webhook-Signature") || ""; const esperada = "sha256=" + crypto.createHmac("sha256", process.env.LEAPER_WEBHOOK_SECRET) .update(req.body) .digest("hex"); const a = Buffer.from(recebida); const b = Buffer.from(esperada); if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) { return res.sendStatus(401); } const evento = JSON.parse(req.body.toString("utf8")); fila.enfileirar(evento); // processe fora do ciclo da requisição res.sendStatus(200); // responda rápido } );
$corpo = file_get_contents("php://input"); $recebida = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? ""; $esperada = "sha256=" . hash_hmac("sha256", $corpo, getenv("LEAPER_WEBHOOK_SECRET")); if (!hash_equals($esperada, $recebida)) { http_response_code(401); exit; } $evento = json_decode($corpo, true); enfileirar($evento); http_response_code(200);
import hmac, hashlib, os from flask import request, abort @app.post("/integracoes/leaper") def leaper_webhook(): corpo = request.get_data() # bytes crus recebida = request.headers.get("X-Webhook-Signature", "") esperada = "sha256=" + hmac.new( os.environ["LEAPER_WEBHOOK_SECRET"].encode(), corpo, hashlib.sha256, ).hexdigest() if not hmac.compare_digest(esperada, recebida): abort(401) enfileirar(request.get_json()) return "", 200
Entrega e tentativas
| Regra | Comportamento |
|---|---|
| Método | POST com corpo JSON |
| Sucesso | Qualquer resposta 2xx. O corpo da sua resposta é ignorado |
| Falha | Qualquer outro código, erro de conexão ou estouro de tempo |
| Tempo limite | 10 segundos para a resposta completa, 5 para estabelecer a conexão |
| Tentativas | Até 3 no total. Esgotadas, o evento é marcado como falho e não é reenviado |
| Redirecionamentos | Seguidos, até 3 saltos, só em http e https e nunca para endereço interno |
| User-Agent | Leaper-Webhooks/1.0, a menos que você cadastre o seu nos cabeçalhos extras |
| Webhook pausado | Enquanto estiver pausado, nada é entregue nem guardado para depois |
O tempo limite de 10 segundos vale para a resposta inteira. Se o seu endpoint grava em CRM, dispara e-mail e chama outras APIs antes de responder, ele vai estourar o limite e receber a mesma entrega de novo. Valide a assinatura, guarde o evento numa fila sua, responda 200 e processe depois.
Descartar entrega repetida
Uma entrega pode chegar mais de uma vez: a tentativa que estourou o seu tempo limite pode ter sido processada do seu lado mesmo assim. O campo event_id identifica a entrega e repete nas retentativas da mesma entrega — guarde os que você já processou e descarte o que voltar.
{ "event": "lead_converted", "event_id": "9b35e0c7-4a1d-4f82-b6e9-3c08d7152fa4", "timestamp": "2026-09-03T10:08:33Z", "company": { "id": "6201138c-fc0a-4478-820f-8907907e7f00", "whatsapp_phone": "5511955550100" }, "lead": { "id": "b7d4e1a2-8f3c-4a19-9c62-1e5f0a7d3b84", "name": "Marina Alves", "phone": "5511987654321", "email": "marina.alves@exemplo.com.br", "source": "METAADS_MSG", "tags": "prioridade-alta", "created_at": "2026-09-02 09:14:50", "created_from": null, "lead_value": "3200" }, "status": { "current": { "code": "END_WON", "name": "Finalizado - Convertido", "changed_at": "2026-09-03 10:08:31" }, "previous": { "code": "NEGOCIACAO", "name": "Negociação", "changed_at": "2026-09-02 15:41:05" } }, "tracking": { "source": "METAADS_MSG", "sourceApp": "instagram", "sourceUrl": "https://www.instagram.com/", "sourceType": "ad", "utmSource": null, "utmMedium": null, "utmCampaign": null, "utmContent": null, "utmTerm": null, "referer": null, "pageUrl": null, "device": null, "browser": null, "os": null, "ipAddress": null, "userAgent": null, "country": null, "clickId": "ARAaZv8x1QpKm3nLd0TbYq", "clickIdType": "ctwa_clid", "clickDate": null, "campaignData": null, "formData": null, "journey": null }, "formSubmissions": [], "leadAdsSubmissions": [] }
Eventos diferentes que descrevem o mesmo fato têm event_id diferentes, porque são duas entregas. É o caso de uma conversão para quem assina status_change e lead_converted.
Boas práticas
- Use o code, não o name. Os nomes das etapas podem ser renomeados a qualquer momento no painel, e isso quebraria qualquer regra escrita em cima deles.
- Descarte repetição pelo event_id, e deixe o processamento idempotente.
- Aceite campos novos e valores nulos. Podemos acrescentar campos ao corpo sem aviso; ignore o que o seu sistema não conhece em vez de rejeitar a entrega. Qualquer campo pode vir null quando o dado não existe.
- Assine sempre. Um endpoint que aceita qualquer requisição é um endpoint que qualquer pessoa pode alimentar. A verificação são cinco linhas de código.
- Prefira um webhook por finalidade. Separar por destino é mais simples de operar do que um endereço único que recebe tudo e distribui internamente, e permite pausar uma integração sem afetar as outras.
Acompanhar entregas
O painel guarda o histórico do que foi enviado, com filtros por webhook, por lead, por evento, por situação e por período. É por ali que se descobre, por exemplo, que as entregas pararam porque o certificado do servidor venceu.
| Situação | O que significa |
|---|---|
| Na fila | O evento foi registrado e aguarda o envio ou uma nova tentativa |
| Entregue | O seu sistema recebeu e confirmou. Nada a fazer |
| Falhou | As tentativas se esgotaram sem confirmação, ou o webhook estava pausado na hora do envio |
Ao lado de cada tentativa fica o registro do que aconteceu — o código que o seu servidor devolveu ou o erro de conexão. Um 401 costuma ser cabeçalho de autenticação faltando, um 404 é endereço errado, um 405 é endpoint que não aceita POST (só GET), e tempo esgotado quase sempre significa que o endpoint está processando antes de responder.
