Webhooks

Los webhooks son la forma en que la plataforma notifica a tus sistemas cuando algo ocurre — una llamada empezó, una sesión terminó, un goal se alcanzó. Te suscribes por URL; la plataforma hace POST de un payload JSON a esa URL cuando el evento se dispara.

Esta página describe los eventos, el contrato de entrega y el esquema de firma. Las suscripciones se gestionan en la pestaña Webhooks de tu proyecto.

Catálogo de eventos

Hoy hay cinco eventos:

• session.started — se dispara cuando una llamada conecta y el agente empieza a hablar. Lleva el id de sesión, el id de scenario, la dirección (entrante/saliente), el número de teléfono del llamante enmascarado (p. ej. +3412•••789 — el número completo está disponible vía GET /v1/sessions/{id}) y si es una sesión de prueba.
• session.ended — se dispara cuando la llamada termina. Lleva el id de sesión, el estado final (completed / abandoned / failed), la duración y si el goal se alcanzó. Recupera el registro completo de la sesión — transcripción, slots, resultado — vía GET /v1/sessions/{id}.
• session.failed — se dispara cuando la sesión terminó en error. Lleva el id de sesión y el motivo del fallo.
• goal.achieved — se dispara en el momento en que el agente alcanza el goal del scenario, a mitad de llamada, una vez por sesión. El payload incluye la definición del goal y los valores de slots capturados hasta ese punto. Úsalo para efectos secundarios que quieras de inmediato, no al final de la sesión.
• intent.classified — se dispara cuando el clasificador de intención elige un scenario en un proyecto con varios scenarios. Útil para auditoría y para medir la precisión del enrutado.

Los webhooks cubren hoy las sesiones de voz; los eventos de conversaciones de mensajería y de finalización de lotes están en la hoja de ruta.

Suscribirse

En la pestaña Webhooks del proyecto, crea una suscripción:

• URL — donde recibes los POST. Debe ser HTTPS.
• Eventos — elige del catálogo. Un evento, varios o todos.

La plataforma muestra el secreto de firma una sola vez, al crearla — cópialo a tu entorno. No puedes recuperarlo después; puedes rotarlo, lo que reemplaza el secreto de inmediato (actualiza primero tu endpoint, luego rota).

Puedes tener hasta 10 suscripciones por proyecto.

Formato del payload

Cada payload es JSON y comparte este sobre:

{
  "event": "session.ended",
  "deliveryId": "5b2c4f8a-…",
  "ts": "2026-05-13T18:42:11Z",
  "tenantId": "…",
  "projectId": "…",
  "data": { … }
}

El esquema del objeto data es específico de cada evento. Las entregas son al-menos-una-vez, y deliveryId es estable entre los reintentos de un mismo evento — úsalo para idempotencia en tu lado.

Firma

Cada petición lleva estas cabeceras:

• x-avp-signature — sha256=<hex> donde el valor hex es un HMAC-SHA256 del cuerpo crudo de la petición, con el secreto de firma de tu suscripción como clave.
• x-avp-event — el tipo de evento, para que puedas enrutar antes de parsear.
• x-avp-timestamp — cuándo se envió la entrega.
• x-avp-subscription-id — a qué suscripción pertenece esta entrega.
• x-avp-delivery-id — el mismo valor que deliveryId en el cuerpo.

Verifica la firma en cada petición: calcula el HMAC del cuerpo crudo con tu secreto y compáralo con la cabecera. Una comparación de cadenas en tiempo constante es obligatoria — un == ingenuo es vulnerable a ataques de temporización. Rechaza todo lo que no coincida.

Reintentos y fiabilidad

• Entrega al-menos-una-vez: el mismo evento puede llegar más de una vez. Usa deliveryId para idempotencia.
• Timeout: 10 segundos. Si tu endpoint tarda más, la entrega cuenta como fallida.
• Política de reintentos: el primer intento es inmediato, luego 5 reintentos con backoff creciente (1 min → 5 min → 15 min → 1 h → 6 h). Tras el último reintento, la entrega se descarta y se registra.
• Desactivación automática: si una suscripción sigue fallando de forma permanente (50+ entregas descartadas en 24 horas), la plataforma la desactiva. La reactivas desde la pestaña Webhooks tras arreglar tu endpoint.

La pestaña Webhooks muestra el registro de entregas de cada suscripción — cada intento, el estado de la respuesta, la latencia, un extracto de la respuesta de tu endpoint. También hay una acción de enviar entrega de prueba para que verifiques tu endpoint antes de que le llegue tráfico real.

Webhooks entrantes (la otra dirección)

También puedes empujar eventos hacia conversaciones en vivo. Crea un webhook entrante en tu proyecto con un nombre; la plataforma te da una URL y un secreto de firma dedicado (mostrado una sola vez).

POST /v1/projects/{project_id}/webhooks/{name}
x-avp-signature: sha256=<hex-hmac-of-raw-body>
Content-Type: application/json

Firma el cuerpo crudo con el secreto del webhook entrante, el mismo esquema HMAC-SHA256 que las entregas salientes. El cuerpo se entrega a cada sesión del proyecto activa cuando llega la petición, como un evento de intercept on_webhook_received; un script asociado a ese evento lee el payload y decide qué hacer — avisar al agente a mitad de llamada de que un pedido se envió, empujar un cambio de precio a una consulta en vivo, disparar un tool call desde fuera.

Límites: 25 nombres de webhook entrante por proyecto. Las peticiones a un nombre que no existe devuelven 404; las sesiones sin un manejador on_webhook_received ignoran el evento.