Events and realtime
The event catalog, polling as the backstop, and a subscribe-only channel for the moments you want live.
Every state change writes an event. Events are the record of what happened and the payload every webhook carries, and they are the same rows whether you receive them by webhook, read them back, or watch them arrive on a channel.
The shape
{
"id": "evt_2b7c9d10",
"type": "case.approved.v1",
"created_at": "2026-09-08T14:07:44Z",
"organization": "org_c8k2q1w9",
"mode": "test",
"resource": { "type": "case", "id": "case_7d1e4b2a" },
"status": "approved",
"previous_status": "in_review"
}
Events are thin by design: ids, type, status and timestamps. status is the resource's status
after the transition, so a delivery that arrives out of order is still safe to apply.
data carries the resource as it stood at that moment only in test mode, when the endpoint has
include_resource on or you asked for it on the query. A live event is always thin, whatever either
setting says: no snapshot of a live resource is stored with its event, so read the resource back by
its id when you need more than the status.
The catalog
Each type is versioned. A payload change ships as a new type rather than a silent break.
| Group | Types |
|---|---|
| Patient | patient.created.v1, patient.updated.v1, patient.deleted.v1 |
| Case | case.received.v1, case.queued.v1, case.visit_required.v1, case.in_review.v1, case.waiting_on_patient.v1, case.waiting_on_integration.v1, case.approved.v1, case.declined.v1, case.cancelled.v1, case.withdrawn.v1 |
| Thread | case.question_asked.v1, case.message_created.v1 |
| Prescription | prescription.created.v1, prescription.updated.v1 |
| Order | order.created.v1, order.at_pharmacy.v1, order.shipped.v1, order.delivered.v1, order.blocked.v1, order.failed.v1 |
| Visit | visit.booked.v1, visit.rescheduled.v1, visit.cancelled.v1, visit.started.v1, visit.completed.v1, visit.no_show.v1 |
| Lab | lab_order.created.v1, lab_order.placed.v1, lab_order.status_changed.v1, lab_result.final.v1 |
| Purchase | purchase.paid.v1, purchase.refunded.v1, purchase.disputed.v1 |
| Affiliate | affiliate.created.v1, affiliate.updated.v1, affiliate_referral.created.v1, affiliate_referral.updated.v1 |
| Membership | membership.activated.v1, membership.renewed.v1, membership.payment_failed.v1, membership.cancelled.v1, membership.lapsed.v1 (emitted from Wave B) |
| Commission | affiliate_commission.created.v1, affiliate_commission.updated.v1 (emitted from Wave B) |
| Other | consent.recorded.v1, file.attached.v1, charge.created.v1, webhook_endpoint.disabled.v1 |
The seven types marked "emitted from Wave B" are published, so an endpoint may subscribe to them today, and nothing emits them until that wave lands.
case.visit_required.v1 means a change to the patient's state left an open case needing a live
video visit there. The case is held, so its status is received, and its intake is kept: book
POST /v1/visits with case set to it. It is sent once, when the change puts the hold on, and
never for a case a booked visit will decide. The event is never billed. See Cases.
A visit event's resource is { "type": "visit", "id": "vis_…" } and its status is the status
the visit holds afterwards. visit.rescheduled.v1 carries scheduled on both status and
previous_status, because a move changes the hour rather than the state. See
Visits.
A lab order event's status is the order's status when the event was written (placed,
collecting, at_lab, final, cancelled, failed, or awaiting_patient after a re-order);
GET /v1/lab_orders/{id} is the current truth. An order is first announced when it is placed: one
still waiting on the patient is not, so list GET /v1/lab_orders?updated_after= to see those. An
order a clinician requested during a case review also carries case, so it is listed by
GET /v1/cases/{id}/events. Lab events never carry patient: read it from the order.
lab_result.final.v1 fires once per released version of a report, the moment the patient can see
it, and carries no status, case or patient. A correction is a new result with a higher version on
the same lab order, announced with its own lab_result.final.v1, and supersedes the earlier one;
GET /v1/lab_orders/{id}/results lists them newest first. Read GET /v1/lab_results/{id} with
labs:read for its values, its lab order and a PDF link.
Lab events reach an integration only when the organization's grant includes labs:read. See
Labs.
The commerce events follow the same rule with their own read scopes. Purchase and membership events
reach an integration only when the organization's grant includes purchases:read, and affiliate,
referral and commission events only when it includes affiliates:read. A grant without the scope
never receives them: they are not written for that integration at all, so they never appear on
GET /v1/events, on a webhook or on the realtime channel either.
purchase.paid.v1 fires exactly once per purchase. purchase.refunded.v1 carries
partially_refunded or refunded as its status, and purchase.disputed.v1 carries none. Read
GET /v1/purchases/{id} for the rest. See Purchases and
Affiliates.
Polling
GET /v1/events needs events:read and is the backstop for a webhook you missed. It is the one
call you should be able to run after an outage and catch up completely.
curl "https://api.cuvo.co/v1/events?since=2026-09-08T00:00:00Z&type=case.approved.v1&limit=100" \
-H "Authorization: Bearer cuvo_sk_test_…"
sincereturns events created strictly after that moment. Keep thecreated_atof the last event you processed and pass it back.typefilters to one type.include_resource=trueembeds the resource in test mode, saving you a read per event. Live events stay thin.limitandstarting_afterpage it. See Pagination.
GET /v1/events/{id} reads one. GET /v1/cases/{id}/events reads a single case's events and needs
cases:read instead.
POST /v1/events/{id}/redeliver queues an event for delivery again, to every subscribed endpoint or
to one you name. It needs webhooks:manage.
Realtime
Realtime is a notification, not a delivery guarantee. Everything on the channel was persisted as an event first, so a client that misses a message loses nothing it cannot poll for. Use it to make a dashboard move, and use webhooks or polling for anything you act on.
POST /v1/realtime/tokens needs realtime:subscribe and takes no inputs: the credential and its
organization already name the channel.
{
"token": "…",
"channel": "integration:int_5a1c:org_c8k2q1w9:test",
"capability": "subscribe",
"mode": "test",
"expires_at": "2026-09-08T15:07:44Z"
}
The token is Ably's, lives one hour, and grants subscribe on that one literal channel. Publish is
never granted, so nothing on the channel can be invented by a client. Test mode is a separate
channel with a :test suffix rather than a flag inside the message, so a sandbox event can never
reach a listener that only asked for live traffic.
Each message is named after the event type and carries the same event body the webhook would. Subscribe with any Ably client, minting a fresh token when the last one expires.