Webhooks

Events OlivIA sends to your backend, their payloads, and the delivery policy

Webhooks let your backend receive real-time notifications of what happens during calls.

Webhooks are not registered from the external API: they are configured in the platform (or with the Omniloy team) and attached to a protocol version. This page documents the events you will receive and how they are delivered.

Events

Event	When it fires	Filter
session.start	When the call session starts	—
session.teardown	When the session closes	—
run.status_changed	On every questionnaire status change	target_statuses[]
question.answered	When an answer is captured	question_keys[]
call.transferred	When the call is transferred to a human	—
number.to_verify	When a wrong number is detected	—

Payloads

The payload is built per event and includes the questionnaire and protocol context. Answers and transcriptions have the same shape the read endpoints return, so you can handle them with the same code wherever they came from.

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": "Have you had trouble breathing?",
      "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": "Have you had a fever?",
      "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[] carries one entry per question the questionnaire reached, in the order the patient heard them:

Field	Description
question_key, question_text	The question’s stable key and its wording, resolved to the questionnaire’s language.
status	answered means it was answered; declined means it was put and the patient would not answer; asked means it was put and the call never captured an answer.
value	Typed by type: number, text, boolean, ISO date, or the option_keys picked. null when there was no answer.

question.answered delivers that same entry for a single question, without the timestamps or call_id:

{
  "question_key": "disnea",
  "question_text": "Have you had trouble breathing?",
  "type": "multiple_choice",
  "status": "answered",
  "value": ["mucha-dificultad"]
}

This event carries the value as it stood when it was captured, even if the question is answered again later. That is why it has no timestamps and no call_id: those live on a row that is rewritten on a re-answer, and reporting them here would pair one answer’s timing with another answer’s value. When you need the questionnaire’s full, self-consistent picture, read it with GET /v1/protocol-runs/{runId}.

Questions and options travel by key, never by internal identifier: keys are stable across versions and do not change if someone rewrites the wording.

Payloads do not include patient personal data unless the event explicitly requires it (e.g. number.to_verify, which carries patient_id and phone). To link a run to a patient, join on run.enrollment_id.

Authentication to your endpoint

OlivIA does not sign the body with HMAC. Instead, each webhook authenticates against your endpoint with the credentials you configure. Options:

Type	Effect
bearer	Authorization: Bearer <token>
basic	Authorization: Basic <base64>
api_key	Custom header <header_name>: <value>
oauth2_client_credentials	OlivIA fetches a token from token_url and sends it

Secrets are encrypted at rest (AES-256-GCM) and shown masked. Protect your endpoint by validating these credentials.

Delivery and retries

• Best-effort delivery; every attempt is recorded.
• Configurable retries: max_retries (0–10) and timeout_ms (100–60000, default 10000).
• Retried on network errors, timeouts, and 5xx responses. Not retried on 4xx. Redirects are not followed.