Skip to content

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.

GroupTypes
Patientpatient.created.v1, patient.updated.v1, patient.deleted.v1
Casecase.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
Threadcase.question_asked.v1, case.message_created.v1
Prescriptionprescription.created.v1, prescription.updated.v1
Orderorder.created.v1, order.at_pharmacy.v1, order.shipped.v1, order.delivered.v1, order.blocked.v1, order.failed.v1
Visitvisit.booked.v1, visit.rescheduled.v1, visit.cancelled.v1, visit.started.v1, visit.completed.v1, visit.no_show.v1
Lablab_order.created.v1, lab_order.placed.v1, lab_order.status_changed.v1, lab_result.final.v1
Purchasepurchase.paid.v1, purchase.refunded.v1, purchase.disputed.v1
Affiliateaffiliate.created.v1, affiliate.updated.v1, affiliate_referral.created.v1, affiliate_referral.updated.v1
Membershipmembership.activated.v1, membership.renewed.v1, membership.payment_failed.v1, membership.cancelled.v1, membership.lapsed.v1 (emitted from Wave B)
Commissionaffiliate_commission.created.v1, affiliate_commission.updated.v1 (emitted from Wave B)
Otherconsent.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_…"
  • since returns events created strictly after that moment. Keep the created_at of the last event you processed and pass it back.
  • type filters to one type.
  • include_resource=true embeds the resource in test mode, saving you a read per event. Live events stay thin.
  • limit and starting_after page 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.