Webhooks salientes

Si tu stack no es ninguna integración nativa (HubSpot, Pipedrive, Slack) los webhooks salientes te permiten recibir cualquier evento de LeadsBase en tu propio backend. Útil para conectar con Salesforce, sistemas a medida o data lakes.

1. Crear un endpoint

Configura un endpoint HTTPS público que acepte POST con body JSON. Recomendaciones:

• TLS 1.2 mínimo. Rechazamos automáticamente HTTP plano.
• Responder con 2xx en menos de 10 segundos. Si tardas más, marcamos como fallo y reintentamos.
• Idempotencia por event_id: si recibes el mismo evento dos veces (por reintento), no proceses dos veces.

2. Registrar el webhook

En Ajustes → Webhooks → Nuevo webhook:

1. URL destino: tu endpoint público.
2. Eventos suscritos: marca solo los que necesites para evitar tráfico innecesario.
3. Secret: genera un secret aleatorio que usaremos para firmar payloads.

Eventos disponibles (selección):

• company.created, company.updated, company.archived
• enrichment.completed, enrichment.failed
• map.new_companies
• rgpd.suppression
• billing.invoice_paid, billing.payment_failed
• api_key.created, api_key.revoked

3. Firma de payload (HMAC-SHA256)

Cada request incluye cabecera X-LeadsBase-Signature con la firma HMAC-SHA256 del body usando tu secret. Verifica antes de procesar:

import hmac
import hashlib

def verify(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Si la firma no coincide, rechaza la request. No basta con autenticar por IP porque emitimos desde un pool dinámico.

4. Payload tipo

Todos los eventos comparten estructura base:

{
  "event_id": "evt_2HxK9aBp...",
  "event_type": "company.updated",
  "occurred_at": "2026-05-17T14:32:11.000Z",
  "workspace_id": "ws_8Yg7...",
  "data": {
    "cif": "B12345678",
    "razon_social": "Ejemplo Tech SL",
    "changes": {
      "empleados_tramo": { "old": "10-49", "new": "50-249" }
    }
  }
}

Cada event_type tiene su shape específico documentado en la referencia de la API.

5. Reintentos automáticos

Si tu endpoint devuelve 5xx o no responde en 10s, reintentamos con backoff exponencial:

• 1er reintento: 30 segundos después.
• 2º reintento: 5 minutos.
• 3º reintento: 30 minutos.
• 4º reintento: 2 horas.
• 5º reintento: 12 horas.

Si tras 5 reintentos sigue fallando, marcamos el webhook como inestable y enviamos email al owner. Tras 48h sin recuperación, lo pausamos automáticamente para no saturar tu sistema.

6. Replay manual

En Ajustes → Webhooks → Logs ves cada delivery con status, response code y tiempo. Para reenviar un evento concreto pulsa Replay. Útil para:

• Recuperarte de un downtime puntual.
• Probar cambios en tu endpoint con tráfico real.

7. Eventos de prueba

Cada webhook tiene un botón Enviar evento de prueba que dispara un payload webhook.test con datos ficticios. Úsalo durante el desarrollo para validar firma, parsing y idempotencia antes de activar eventos reales.

8. Buenas prácticas

• Responde 200 inmediato y procesa en cola (Sidekiq, BullMQ, etc.). No dejes el processing dentro del handler HTTP.
• Loguea event_id: te ayudará a depurar y a sincronizar con nuestros logs.
• Maneja company.archived explícitamente: cuando archivamos por supresión RGPD necesitas eliminar el dato en tu sistema también.

Si tu firewall bloquea IPs dinámicas, podemos asignarte un rango fijo de salida (planes Enterprise). Solicítalo a hello@leadsbase.es.

Para troubleshooting de respuestas inesperadas, ver errores comunes API.