Skip to main content
Los webhooks de DeltaLead entregan solicitudes HTTP POST al servidor en el mismo momento en que ocurre algo relevante en la cuenta: llega un lead nuevo, un agente de IA califica un lead o se agenda un test drive. En lugar de consultar la API de forma periódica, los sistemas reciben los datos del evento en tiempo real y sin latencia adicional, lo que permite disparar flujos posteriores, actualizar una base de datos propia o avisarle al equipo de ventas en el instante en que aparece un lead caliente.

Registrar un endpoint de webhook

1

Abrir la configuración de webhooks

En el panel de DeltaLead, ir a Configuración → Webhooks → Agregar endpoint. Como alternativa, se puede llamar directamente a POST /v1/webhooks desde la API.
2

Indicar la URL del endpoint

Se indica la URL HTTPS completa del servidor que va a recibir los eventos. Los endpoints con HTTP simple no se aceptan: DeltaLead exige un certificado TLS válido.
3

Seleccionar los eventos

Se eligen los tipos de evento a los que conviene suscribirse. Suscribirse solo a los eventos que la integración necesita reduce el tráfico innecesario hacia el servidor. La referencia completa de eventos enumera todos los tipos disponibles.
4

Guardar y copiar el secreto

Al guardar, DeltaLead genera un secreto de firma HMAC-SHA256 para el endpoint. Hay que copiarlo de inmediato: se muestra una sola vez. Conviene guardarlo de forma segura en las variables de entorno de la aplicación y usarlo para verificar cada solicitud entrante.

Estructura del payload

Todo POST de webhook que DeltaLead envía al endpoint comparte la misma estructura de nivel superior, sin importar el tipo de evento.
string
Tipo de evento que originó esta entrega, por ejemplo lead.qualified.
string
Marca de tiempo ISO 8601 del momento en que ocurrió el evento en la plataforma de DeltaLead.
string
ID de la organización de DeltaLead asociada al evento.
object
Payload específico del evento. Los campos que contiene data varían según el tipo de evento. La referencia de eventos incluye los esquemas completos.
lead.qualified event

Verificación de firmas de webhook

DeltaLead firma cada solicitud de webhook para demostrar que el payload salió de su plataforma. La firma viaja en la cabecera de solicitud X-DeltaLead-Signature como un digest HMAC-SHA256 codificado en hexadecimal del cuerpo crudo de la solicitud, calculado con el secreto de firma del endpoint. La firma debe verificarse siempre antes de procesar el payload de un webhook. Omitir este paso deja el endpoint expuesto a solicitudes falsificadas.
Conviene usar siempre una comparación de tiempo constante (como crypto.timingSafeEqual en Node.js o hmac.compare_digest en Python) para evitar ataques de temporización contra la verificación de la firma.

Respuesta a los webhooks

El endpoint debe devolver un código de estado HTTP 2xx dentro de los 10 segundos de recibida la entrega. DeltaLead interpreta cualquier respuesta que no sea 2xx —o una solicitud que expire por tiempo— como una entrega fallida.

Política de reintentos

DeltaLead reintenta las entregas fallidas hasta 3 veces con retroceso exponencial. Los intervalos de reintento son de aproximadamente 1 minuto, 5 minutos y 30 minutos después del fallo inicial.

Idempotencia

Como los reintentos pueden generar entregas duplicadas, el manejador debe diseñarse de forma idempotente. El campo data.id sirve para descartar los eventos ya procesados.
Durante el desarrollo local, una herramienta de túnel como ngrok permite exponer el servidor de localhost a internet y recibir eventos reales de webhook de DeltaLead sin necesidad de desplegar en un servidor público.
La referencia de eventos de webhook contiene la lista completa de tipos de evento y sus esquemas de payload.