Send a reading

Post a heart rate above the band as the Submitter app, see the alert arrive at your webhook, then acknowledge it.

Complexity
1/5
Clients
Any HTTP client
Time
10 minutes

Post a reading that breaches the band, watch Signals deliver the alert to your receiver, and acknowledge it. This needs the patient and band from Create a patient and a subscriber from Register a webhook.

.env
OVOK_MANAGER_ID=…
OVOK_MANAGER_SECRET=…
OVOK_SUBMITTER_ID=…
OVOK_SUBMITTER_SECRET=…

Post a breaching readingTerminal

Post a heart rate of 132 /min, above the band's 110, as the Submitter app. The body is a FHIR R4 Observation.

curl --request POST 'https://api.sandbox.ovok.com/v1/signals/api/observation' \
  --user "${OVOK_SUBMITTER_ID}:${OVOK_SUBMITTER_SECRET}" \
  --header 'Content-Type: application/json' \
  --data '{
    "patientRefId": "resident-001",
    "identifier": [{ "system": "urn:example:readings", "value": "reading-0001" }],
    "code": { "coding": [{ "system": "http://loinc.org", "code": "8867-4" }] },
    "valueQuantity": { "value": 132, "unit": "/min" },
    "effectiveDateTime": "2026-10-25T08:00:00Z"
  }'
  • patientRefId is the refId you created the patient with.
  • The identifier makes the post safe to retry: the same one within an hour answers 409 DUPLICATE_READING.
  • Don't send Prefer: respond-sync: it returns the alerts in the answer and sends no webhook for them.

See what arrivesServer-side

Your receiver gets alert.triggered. Its data.id is the alert's id: keep it for the acknowledgement.

{
  "type": "alert.triggered",
  "timestamp": "2026-10-25T08:00:02.000Z",
  "data": {
    "id": "0b9d7e52-1f3a-4e8c-b6a2-7c4d9e1f2a35",
    "patientRefId": "resident-001",
    "observationRefId": "reading-0001",
    "triggerCode": "8867-4",
    "value": 132,
    "message": "Heart rate above 110 /min",
    "episodeId": "e7a1b2c3-d4e5-4f60-8a9b-0c1d2e3f4a5b",
    "acknowledgedAt": null,
    "acknowledgedBy": null,
    "version": 1
  }
}

The payload is trimmed here. Event payloads lists every field.

With episodes on, episode.opened arrives too. Its lastAlertId is the alert above.

{
  "type": "episode.opened",
  "timestamp": "2026-10-25T08:00:02.000Z",
  "data": {
    "id": "e7a1b2c3-d4e5-4f60-8a9b-0c1d2e3f4a5b",
    "patientRefId": "resident-001",
    "code": "8867-4",
    "status": "OPEN",
    "openedAt": "2026-10-25T08:00:00.000Z",
    "closedAt": null,
    "closeReason": null,
    "lastAlertId": "0b9d7e52-1f3a-4e8c-b6a2-7c4d9e1f2a35"
  }
}
  1. 1ovok listen forwards signed Signals events to this machine.
  2. 2Post a heart-rate reading above the configured band.
  3. 3Acknowledge the alert and watch the receiver confirm it.

Acknowledge the alertTerminal

A clinician has seen it. Acknowledge it as the Manager app, with the alert's id from the delivery.

curl --request POST "https://api.sandbox.ovok.com/v1/signals/api/alert/${ALERT_ID}/ack" \
  --user "${OVOK_MANAGER_ID}:${OVOK_MANAGER_SECRET}" \
  --header 'Content-Type: application/json' \
  --data '{"actor":{"reference":"Practitioner/123","display":"Dr. Max Mustermann"}}'

Your receiver gets alert.acknowledged: the same alert id, a higher version, and who acknowledged it.

{
  "type": "alert.acknowledged",
  "timestamp": "2026-10-25T08:00:02.000Z",
  "data": {
    "id": "0b9d7e52-1f3a-4e8c-b6a2-7c4d9e1f2a35",
    "patientRefId": "resident-001",
    "acknowledgedAt": "2026-10-25T08:05:00.000Z",
    "acknowledgedBy": { "reference": "Practitioner/123", "display": "Dr. Max Mustermann" },
    "version": 2
  }
}

The episode closes with ACKNOWLEDGED; the next breach opens a new one.

Verify your integration

You should see alert.triggered and episode.opened within a few seconds of the post, and alert.acknowledged after the acknowledgement. If nothing arrives:

  1. Check the band: GET /tenant shows the triggers (Update tenant settings).
  2. Check the subscriber's reach includes resident-001 and its events include alert.*.
  3. List the events to see what Signals sent and how your server answered. Debugging covers the rest.

Next

Example app puts the receiver, the patient, the reading and the acknowledgement into one program.

Last updated on

On this page