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 solicitudX-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 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. El campo
data.id sirve para descartar los eventos ya procesados.