Webhooks

Eventos que OlivIA envía a tu backend, sus payloads y la política de entrega

Los webhooks permiten que tu backend reciba notificaciones en tiempo real de lo que ocurre durante las llamadas.

Los webhooks no se registran desde la API externa: se configuran en la plataforma (o con el equipo de Omniloy) y se asocian a una versión de protocolo. Aquí documentamos los eventos que recibirás y cómo se entregan.

​

Eventos

Evento	Cuándo se emite	Filtro
session.start	Al iniciarse la sesión de la llamada	—
session.teardown	Al cerrarse la sesión	—
run.status_changed	En cada cambio de estado del cuestionario	target_statuses[]
question.answered	Al capturarse una respuesta	question_keys[]
call.transferred	Cuando la llamada se transfiere a un humano	—
number.to_verify	Cuando se detecta un número equivocado	—

​

Payloads

El payload se construye por evento e incluye el contexto del run y el protocolo. Ejemplos abreviados:

run.status_changed:

{
  "new_status": "completed",
  "previous_status": "in_progress",
  "run": { "id": "…", "questionnaire_status": "completed", "score": 7, "score_class": "medium" },
  "protocol": { "id": "…", "protocol_key": "seguimiento-epoc", "title": "…" },
  "protocol_version": { "id": "…", "version": 3 },
  "answers": [ { "question_key": "disnea", "answer": "sí" } ],
  "calls": [ { "id": "…", "transcription": [ { "speaker": "patient", "content": "…", "occurred_at": "…" } ] } ]
}

question.answered:

{ "question_key": "disnea", "answer": "sí" }

Los payloads no incluyen datos personales del paciente salvo cuando el evento lo requiere explícitamente (p. ej. number.to_verify, que lleva patient_id y phone). Para asociar un run a un paciente, haz join por run.enrollment_id.

​

Autenticación hacia tu endpoint

OlivIA no firma el cuerpo con HMAC. En su lugar, cada webhook se autentica contra tu endpoint con las credenciales que configures. Opciones:

Tipo	Efecto
bearer	Authorization: Bearer <token>
basic	Authorization: Basic <base64>
api_key	Cabecera personalizada <header_name>: <valor>
oauth2_client_credentials	OlivIA obtiene un token del token_url y lo envía

Los secretos se cifran en reposo (AES-256-GCM) y se muestran enmascarados. Protege tu endpoint validando estas credenciales.

​

Entrega y reintentos

• Entrega best-effort; cada intento se registra.
• Reintentos configurables: max_retries (0–10) y timeout_ms (100–60000, def. 10000).
• Se reintenta ante errores de red, timeouts y respuestas 5xx. No se reintenta ante 4xx. Las redirecciones no se siguen.