Configurando o Webhook de Leads
Data de atualização:
O que o webhook faz
O ClickSambo envia cada lead de Formulário instantâneo ao seu endereço HTTPS como JSON, com todos os campos do formulário e a análise de fraude. Seu CRM pode manter os leads reais e filtrar os suspeitos. Cada requisição é assinada com HMAC-SHA256, para que seu sistema confirme que ela veio do ClickSambo.
Como Configurar
1. Acesse Anúncios → Meta Ads → Formulários de Leads → Webhook e notificações.
2. Informe a URL do endpoint (HTTPS).
3. Informe uma Chave de assinatura (secret) com pelo menos 16 caracteres ou clique em Gerar. Defina a mesma chave no seu endpoint.
4. Clique em Verificar e salvar. O ClickSambo só salva o endereço depois que seu endpoint responde corretamente ao handshake de verificação.
Depois de salvar, você pode usar Enviar lead de teste, Pausar, Alterar endpoint ou chave e Remover.
Eventos e Cabeçalhos
| Evento | Quando é enviado |
|---|---|
lead.received | Depois que um novo lead é analisado |
lead.updated | Quando você marca um lead como Real ou Falso |
webhook.test | Quando você clica em Enviar lead de teste |
webhook.verify | Durante o handshake ao salvar |
Cada requisição traz os cabeçalhos X-ClickSambo-Event, X-ClickSambo-Delivery, X-ClickSambo-Timestamp e X-ClickSambo-Signature. A assinatura é sha256= seguido do HMAC-SHA256 em hexadecimal do corpo bruto da requisição, calculado com a sua chave.
Regras de Verificação e Entrega
| Evento / campo | O que fazer |
|---|---|
webhook.verify | Responda com HTTP 200 e um JSON com challenge e signature. A assinatura é sha256= mais o HMAC-SHA256 do valor de challenge com a sua chave. |
lead.received, lead.updated | Responda com HTTP 2xx em até 15 segundos. Outras respostas são tentadas novamente 3 vezes, e você pode reenviar qualquer lead pelo painel. |
analysis.verdict, analysis.fraud_score | Filtre os leads no seu CRM. O veredito é real ou fraud. |
lead.fields | Traz cada pergunta do formulário como foi enviada; e-mail, telefone e nome completo também são normalizados. |
Exemplo de Código
O guia de integração do painel traz exemplos em Node.js, PHP e C# e o modelo completo de payload. Um exemplo em Node.js:
// Node.js (Express) — o corpo bruto é necessário para verificar a assinatura
const crypto = require('crypto');
const SECRET = process.env.CLICKSAMBO_WEBHOOK_SECRET;
app.post('/clicksambo-leads', express.raw({ type: 'application/json' }), (req, res) => {
const raw = req.body.toString('utf8');
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(raw).digest('hex');
const given = req.get('X-ClickSambo-Signature') || '';
if (given.length !== expected.length ||
!crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
return res.status(401).end();
}
const data = JSON.parse(raw);
if (data.event === 'webhook.verify') {
const signature = 'sha256=' + crypto.createHmac('sha256', SECRET).update(data.challenge).digest('hex');
return res.json({ challenge: data.challenge, signature });
}
if (data.event === 'lead.received' || data.event === 'lead.updated') {
if (data.analysis.verdict === 'real') saveToCrm(data.lead); // mantém os leads reais
else moveToQuarantine(data.lead, data.analysis); // separa os suspeitos
}
res.status(200).end();
});