Guia · Webhooks

Webhooks assinados, com retry.

Receba eventos de play, retenção, CTA e lead score em qualquer endpoint HTTP. Assinatura HMAC SHA-256, retry exponencial e dead-letter no painel.

Eventos disponíveis

  • play — primeiro play do visitante
  • pause — pausa manual
  • watched_25, watched_50, watched_75, watched_90 — milestones de retenção
  • watched_complete — vídeo terminou
  • cta_click — clique em CTA (botão WhatsApp, formulário, link)
  • form_submit — envio de formulário inline
  • intent_score_threshold — disparo quando score do visitante cruza limiar configurado

Formato do payload

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
X-LeadPlayer-Event: cta_click
X-LeadPlayer-Signature: sha256=abc123...
X-LeadPlayer-Timestamp: 1719234567

{
  "event": "cta_click",
  "video_id": "vid_abc123",
  "visitor_id": "vis_xyz789",
  "session_id": "ses_def456",
  "timestamp": "2026-06-24T13:00:00Z",
  "video_second": 712,
  "intent_score": 78,
  "cta": { "type": "whatsapp", "label": "Falar no WhatsApp" },
  "utm": { "source": "fb", "medium": "cpc", "campaign": "lancamento" },
  "device": "mobile",
  "country": "BR"
}

Verificar a assinatura (Node)

import { createHmac, timingSafeEqual } from "crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = signatureHeader.replace(/^sha256=/, "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Use o raw body (string original), não o JSON parseado — qualquer reformatação muda a assinatura.

Retry e dead-letter

Se seu endpoint retornar status diferente de 2xx, retry com backoff: 1min → 5min → 15min → 1h → 6h → 24h. Após 6 falhas, o evento entra na fila de dead-letter visível no painel (aba Integrações → Logs).

De lá, você pode reprocessar manualmente ou exportar para auditoria.

Perguntas frequentes

Quais eventos vocês enviam?

play, pause, watched_25, watched_50, watched_75, watched_90, watched_complete, cta_click, form_submit, intent_score_threshold.

Qual a estratégia de retry?

Retry exponencial: 1min, 5min, 15min, 1h, 6h, 24h. Após 6 tentativas com falha (status != 2xx), o evento vai para a fila de dead-letter no painel.

Posso testar webhook em desenvolvimento?

Sim. Use ngrok ou Cloudflare Tunnel para expor seu localhost e cadastre a URL no painel. O LeadPlayer envia eventos de teste sob demanda na aba Webhooks.

O payload pode mudar?

Adicionamos novos campos sem quebrar compatibilidade. Mudanças breaking são versionadas via header X-LeadPlayer-Version e comunicadas com 30 dias de antecedência.

Pronto para testar no seu vídeo?

Plano grátis sem cartão. Hospede um vídeo, embede no seu site e veja a retenção em minutos. Player sem marca a partir do Pro.