1. Descripción general
El Lead Delivery Webhook entrega cada lead captado por AES a un endpoint externo elegido por el cliente, conforme ocurre. Es la forma más simple de reflejar la captación de AES en un sistema de terceros sin otorgar acceso a la plataforma.
La entrega es de empuje y al menos una vez. Se espera que el endpoint receptor sea idempotente sobre event_id.
2. Configuración
La entrega se configura por entorno y está desactivada por omisión. Se habilita desde el panel de administración del cliente, donde se define la URL de destino y el secreto de firma.
| Ajuste | Descripción |
|---|---|
| URL de destino | Endpoint HTTPS que recibe la carga. |
| Secreto de firma | Secreto compartido con el que se calcula el encabezado de firma. |
| Eventos | Qué eventos del ciclo de vida se entregan. |
| Estado | La entrega permanece apagada hasta habilitarse explícitamente. |
3. Carga
POST {tu_endpoint}
Content-Type: application/json
X-AES-Event: lead.created
X-AES-Signature: sha256=<hmac_hex>
X-AES-Timestamp: 1787923271
{
"event": "lead.created",
"event_id": "evt_71ab30cd",
"lead_id": "AES-38-104772",
"occurred_at":"2026-08-27T14:02:11-06:00",
"contact": {
"name": "María Fernanda Ríos",
"phone_e164": "+5218112345678",
"email": "mfrios@example.com"
},
"origin": {
"channel": "landing_form",
"source": "example.com/norte/servicio",
"campaign": "primavera-norte"
},
"branch_code": "ACME-NORTE",
"fields": {
"message": "Solicitó horario vespertino."
}
}4. Eventos
| Evento | Se envía cuando |
|---|---|
lead.created | Se capta un lead nuevo en cualquier canal. |
lead.updated | Cambian los datos de contacto o los campos de calificación. |
lead.stage_changed | El lead pasa a otra etapa del embudo. |
5. Firma
signature = HMAC_SHA256(secret, timestamp + "." + raw_body)
header = "sha256=" + hex(signature)Rechazar toda petición cuyo timestamp caiga fuera de una ventana de 300 segundos, y comparar firmas en tiempo constante.
6. Entrega y reintentos
AES considera aceptada cualquier respuesta 2xx. Cualquier otro estado, o un tiempo de espera mayor a 10 segundos, se reintenta con retroceso exponencial hasta por 24 horas. Como la entrega es al menos una vez, el endpoint receptor debe deduplicar sobre event_id.
El fallo sostenido durante toda la ventana de reintentos desactiva la entrega y levanta un aviso en el panel del cliente. La entrega se reanuda cuando el endpoint se corrige y se vuelve a habilitar.
7. Control de versiones
Pueden agregarse campos nuevos sin previo aviso y los campos no reconocidos deben ignorarse. Ningún campo se elimina ni cambia de significado dentro de la misma versión mayor.
Contacto
Dudas sobre esta especificación: developers@omb.cloud.