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 cuestionario y del protocolo. Las respuestas y las transcripciones tienen la misma forma que devuelven los endpoints de lectura, así que puedes tratarlas con el mismo código vengan de donde vengan.

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",
      "question_text": "¿Ha tenido dificultad para respirar?",
      "type": "multiple_choice",
      "status": "answered",
      "asked_at": "2026-09-09T10:14:02Z",
      "answered_at": "2026-09-09T10:14:22Z",
      "call_id": "…",
      "value": ["mucha-dificultad"]
    },
    {
      "question_key": "fiebre",
      "question_text": "¿Ha tenido fiebre?",
      "type": "boolean",
      "status": "declined",
      "asked_at": "2026-09-09T10:15:00Z",
      "answered_at": null,
      "call_id": "…",
      "value": null
    }
  ],
  "calls": [ { "id": "…", "transcription": [ { "speaker": "patient", "content": "…", "occurred_at": "…" } ] } ]
}

answers[] lleva una entrada por pregunta que el cuestionario alcanzó, en el orden en que el paciente las oyó:

Campo	Descripción
question_key, question_text	La clave estable de la pregunta y su enunciado, resuelto al idioma del cuestionario.
status	answered la contestó; declined se la puso y no quiso contestar; asked se la puso y la llamada no llegó a recoger respuesta.
value	Tipado por type: número, texto, booleano, fecha ISO, o las option_key elegidas. null si no hubo respuesta.

question.answered manda esa misma entrada para una sola pregunta, sin las marcas de tiempo ni call_id:

{
  "question_key": "disnea",
  "question_text": "¿Ha tenido dificultad para respirar?",
  "type": "multiple_choice",
  "status": "answered",
  "value": ["mucha-dificultad"]
}

Este evento lleva el valor tal como estaba cuando se capturó, aunque la pregunta se vuelva a contestar después. Por eso no incluye marcas de tiempo ni call_id: esos viven en una fila que se reescribe al recontestar, y decirlos aquí sería emparejar el momento de una respuesta con el valor de otra. Cuando necesites la foto completa y coherente del cuestionario, léela con GET /v1/protocol-runs/{runId}.

Las preguntas y las opciones viajan por clave, no por identificador interno: las claves son estables entre versiones y no cambian si alguien reescribe el enunciado.

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.