Webhooks

Receba notificações em tempo real quando eventos importantes acontecem no sistema. Webhooks são chamadas HTTP POST enviadas para sua URL quando leads são criados, atualizados ou quando tags são alteradas.

O que são Webhooks?

Em vez de você ficar consultando a API para saber se algo mudou (polling), nós enviamos uma notificação para você quando algo acontece.

❌ Sem Webhooks (Polling)

Você fica perguntando: "Tem lead novo? Tem lead novo?" a cada X segundos.

✅ Com Webhooks

Nós avisamos: "Olha, acabou de chegar um lead novo!" quando acontece.

Como Configurar

Acesse as configurações do integrador

No dashboard, navegue até Configurações → Integradores → [Seu Integrador].

Configure a URL do webhook

Informe a URL do seu servidor que receberá as notificações e selecione os eventos desejados.

Salve e copie o Secret

Ao salvar, um webhook secret será gerado. Use-o para validar as requisições.

Atenção

O secret é exibido apenas uma vez. Guarde-o em local seguro (variável de ambiente).

Eventos Disponíveis

Selecione apenas os eventos que você precisa para evitar processamento desnecessário.

🔗Magic Link (7 eventos)

MAGIC_LINK_CREATEDMagic link criado

MAGIC_LINK_SENTMagic link enviado

MAGIC_LINK_OPENEDMagic link aberto

MAGIC_LINK_CLICKEDLink clicado

MAGIC_LINK_FORM_STARTEDFormulário iniciado

MAGIC_LINK_FORM_COMPLETEDFormulário preenchido

MAGIC_LINK_EXPIREDMagic link expirado

👤Lead (9 eventos)

LEAD_CREATEDLead criado

LEAD_UPDATEDLead atualizado

LEAD_DELETEDLead excluído

LEAD_STATUS_CHANGEDStatus alterado

LEAD_ASSIGNEDAtribuído a usuário

LEAD_UNASSIGNEDDesatribuído

LEAD_TAG_ADDEDTag adicionada

LEAD_TAG_REMOVEDTag removida

LEAD_CONVERTEDConvertido em cliente

📇Contact (6 eventos)

CONTACT_CREATEDContato criado

CONTACT_UPDATEDContato atualizado

CONTACT_DELETEDContato excluído

CONTACT_MERGEDContatos mesclados

CONTACT_EMAIL_CHANGEDEmail alterado

CONTACT_PHONE_CHANGEDTelefone alterado

Estrutura do Payload

Todo webhook enviado possui a seguinte estrutura:

JSON

{
  "event": "LEAD_CREATED",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "webhookId": "wh_abc123",
  "clientId": "client_xyz",
  "data": {
    // Dados específicos do evento
    "lead": {
      "id": "lead_123",
      "externalId": "seu_id_123",
      "status": "open",
      "contact": {
        "name": "João Silva",
        "email": "joao@email.com"
      },
      "tags": ["interessado"]
    }
  }
}

Headers da Requisição

Campo	Tipo	Descricao
`Content-Type`	string	Sempre application/json
`X-Webhook-Id`	string	ID único do webhook
`X-Webhook-Event`	string	Nome do evento (ex: LEAD_CREATED)
`X-Webhook-Timestamp`	string	Timestamp ISO do envio
`X-Webhook-Signature`	string	Assinatura HMAC-SHA256 para validação

Validação de Assinatura

Sempre valide a assinatura para garantir que o webhook veio do ADS-Tools. A assinatura é calculada como HMAC-SHA256(payload, secret).

Exemplos de Validação

NODE

const crypto = require('crypto');

function validateWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === expectedSignature;
}

// Uso
const isValid = validateWebhook(
  req.body,
  req.headers['x-webhook-signature'],
  process.env.WEBHOOK_SECRET
);

Importante

Rejeite webhooks com assinatura inválida retornando status 401.

Política de Retry

Se sua URL retornar erro (status ≥ 400 ou timeout), tentaremos novamente:

1ª tentativa: Imediatamente
2ª tentativa: Após 1 minuto
3ª tentativa: Após 5 minutos
4ª tentativa: Após 30 minutos
5ª tentativa: Após 2 horas

Após 5 tentativas falhas, o webhook é marcado como falho e requer reenvio manual.

Boas Práticas

Responda com 200 OK rapidamente (< 5 segundos)

Processe o webhook de forma assíncrona (fila/background job)

Implemente idempotência usando o webhookId

Sempre valide a assinatura antes de processar

Fazer processamento demorado antes de responder

Ignorar a validação de assinatura

Exemplo de Endpoint

Exemplo de endpoint que recebe webhooks com validação de assinatura:

TypeScript

// Express.js example
app.post('/webhooks/ads-tools', express.json(), async (req, res) => {
  // 1. Validar assinatura
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // 2. Responder rapidamente
  res.status(200).json({ received: true });
  
  // 3. Processar em background
  const { event, data, webhookId } = req.body;
  
  // Checar idempotência
  if (await isWebhookProcessed(webhookId)) {
    return; // Já processado
  }
  
  // Processar evento
  switch (event) {
    case 'LEAD_CREATED':
      await handleLeadCreated(data.lead);
      break;
    case 'LEAD_TAG_ADDED':
      await handleTagAdded(data.lead, data.tag);
      break;
    // ... outros eventos
  }
  
  await markWebhookProcessed(webhookId);
});