Saltar al contenido principal
La API REST está en acceso anticipado y se habilita por cuenta a pedido. Las claves de API no se emiten todavía desde el panel. Para solicitar acceso, contactar al ejecutivo de cuenta.
Los webhooks salientes de DeltaLead entregan solicitudes HTTP POST al servidor del integrador 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 propios 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. Esta página describe una sola dirección: DeltaLead envía eventos hacia un endpoint propio. El sentido inverso —mandar leads desde un sistema externo hacia DeltaLead— lo cubre el Custom Webhook, que sí está disponible hoy.

Registrar un endpoint de webhook

1

Abrir la configuración de webhooks

En el panel de DeltaLead, ir a Organización → Integraciones → Custom Webhooks, dentro de la categoría APIs y Webhooks.
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 de firma

Al guardar, DeltaLead genera un secreto de firma HMAC-SHA256 para el endpoint y lo muestra una sola vez. Ese secreto sirve para verificar cada solicitud entrante y conviene guardarlo en las variables de entorno de la aplicación.Este paso todavía no se puede ejecutar. La pantalla Custom Webhooks emite hoy claves de entrada (dl_live_...), que autentican los envíos hacia DeltaLead y no verifican firmas salientes. Hasta que exista el registro de endpoints salientes, no hay forma de obtener un secreto de firma desde el panel.

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. Cada entrega lleva dos cabeceras.
string
Digest HMAC-SHA256 codificado en hexadecimal, calculado con el secreto de firma del endpoint.
string
Marca de tiempo Unix en segundos del momento del envío. Forma parte del valor firmado.
Lo que se firma no es el cuerpo solo, sino la marca de tiempo, un punto y el cuerpo crudo de la solicitud:
La verificación tiene dos pasos y ninguno es opcional. Primero se compara la marca de tiempo contra el reloj del servidor y se rechaza toda entrega que se aparte más de 5 minutos; después se recalcula el HMAC sobre esa misma concatenación. El HMAC solo prueba de dónde salió el payload, no que sea reciente: sin la ventana de tolerancia, una firma capturada sigue siendo válida para siempre y cualquiera que haya visto una entrega puede reproducirla indefinidamente. Cada reintento se firma de nuevo con una marca de tiempo propia, de modo que la ventana no rechaza reintentos aunque lleguen media hora después del primer intento.
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. La combinación de event y el identificador del recurso en data 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 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.