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.
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.
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 HTTP2xx 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.