Webhooks salientes

Los eventos

• lead.created — un visitante dejo sus datos.
• conversation.completed — alguien marco una conversacion como cerrada o escalada.
• document.indexed — un documento termino de indexarse y ya sirve para responder.
• document.failed — un documento no se pudo indexar.
• sync.completed — una fuente conectada termino una sincronizacion.

Anadir un endpoint

En Destinos → Webhooks, anade una URL https publica y marca los eventos que quieras. El secreto de firma se muestra una sola vez, al crear el endpoint y cada vez que lo rotas. Guardalo entonces; despues solo conservamos su hash.

Usa Enviar una prueba para lanzar un envio real con datos de ejemplo: misma firma, mismos reintentos, mismo registro.

El sobre

Enviamos JSON por POST con dos cabeceras que importan:

X-WelcomeAI-Signature: t=1788639323,v1=6f3a...
X-WelcomeAI-Event: lead.created

El cuerpo tiene esta forma:

{
  "id": "evt_2b91Ha0Kd3fQ",
  "type": "lead.created",
  "created_at": "2026-09-05T20:15:23.201Z",
  "org_id": "org_UWzIf5jv8lW2",
  "data": { "lead_id": "ld_GSTPfNF6SEkE", "email": "grace@example.com" }
}

Verificar un envio

Coge t y v1 de la cabecera de firma. Calcula HMAC-SHA256 sobre la marca de tiempo, un punto y el cuerpo tal cual llego, con tu secreto. Compara con v1 en tiempo constante, y rechaza cualquier cosa donde t tenga mas de cinco minutos.

const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

Usa el cuerpo tal cual, no un objeto reserializado: cualquier diferencia de espacios o de orden de claves cambia el digest.

Reintentos

Lo intentamos seis veces: a los 30 segundos, 2 minutos, 10 minutos, 1 hora, 6 horas y 24 horas. Cada intento se firma de nuevo, asi que un reintento nunca llega con una marca de tiempo caducada.

Cualquier codigo 2xx cuenta como entregado. 410 Gone significa deja de enviar y no reintentamos. Todo lo demas se reintenta, incluidos los 4xx, porque un receptor con un despliegue roto no deberia perder eventos.

Un endpoint que falla veinte veces seguidas se apaga, y puedes volver a encenderlo cuando el receptor este arreglado.

Duplicados

El mismo id de evento puede llegar mas de una vez, por ejemplo si se perdio tu confirmacion. Usa id como clave para deduplicar.