Skip to main content
This is the reference for the prescription webhook events that carry order status and tracking to you. Order status and tracking teaches how to use them; this page lists exactly what they contain. They are signed webhooks, delivered by the same pipeline, envelope and signature scheme as every other OpenLoop event — see Events for the envelope, the Standard Webhooks signature and the delivery policy. Delivery is configured per customer: your OpenLoop implementation contact registers your HTTPS endpoint and returns the signing secret.

What you’ll do

1

Know the four lifecycle events

prescription.created, prescription.ordered, prescription.shipped, prescription.cancelled, at 1.0. The four billing events arrive separately, at 2.0.
2

Read status from the payload

data.status is the lifecycle stage; data.timestamps.* accumulate; data.tracking_ref and data.carrier carry tracking once it ships.
3

Verify and dedupe

Verify the signature (see Events), then dedupe on the envelope id and order by occurredAt.
4

Do not assume what is not written

Payment state is not on these events; data.context keys are not part of the versioned contract.

The events

Four lifecycle verbs are delivered at 1.0. Each carries the same data shape and differs only in data.status and which data.timestamps.* field it sets:
Four billing verbs, prescription.invoiced, .paid, .refund_requested and .changed, are delivered at 2.0 only, so a 1.0 subscription does not receive them; see Events for their versions. prescription.delivered is not produced today. The payment itself is read from the billing events (invoice.paid, subscription.*) or synchronously via GET /v0.1/subscriptions and GET /v0.1/invoices (see Payments and checkout).

Recipe 4.5 · Parse an event

Every event is the full current state of one prescription. Verify the signature, look up your record by data.resource_id, and drop the event if you have already applied its envelope id.
prescription.shipped (synthetic)

data attributes

The payload is com.openloop.prescriptions at eventVersion 1.0. Names are snake_case exactly as below. Required means the key is always present; a Nullable key may carry null.

status values

data.status is the canonical lifecycle stage, one of: created, ordered, shipped, delivered, cancelled, unknown. delivered is defined in the schema but no producer emits it today — the last status you will see is shipped. Each event carries its matching value (e.g. prescription.shipped carries shipped). Render from data.status and the populated data.timestamps.*, not from the event type string.

Handle the dates

They accumulate per order. Each timestamps.* field is absent until its stage happens, then stays populated on every later event for that order. timestamps.ordered_at, for example, first appears on prescription.ordered and is still there on prescription.shipped, so within one order a missed event does not lose a milestone. One prescription (resource_id) can have more than one order, and each order’s events carry only that order’s timestamps, so the latest event does not always carry the prescription’s whole history. Merge the timestamps of every event for the resource_id, keeping the first value set for each timestamp, and see the Events page for the cancel and out-of-order cases. One format. Every timestamp — occurredAt, occurred_at and every timestamps.* — is a UTC ISO-8601 datetime (YYYY-MM-ddTHH:mm:ss.sssZ). There is no date-only or local-timezone field. Order events for the same resource_id by occurredAt, not by arrival. An event older than the one you have already applied is history, not the current state.

Linking to the charting note

data.charting_note_id is the clinician’s charting note the prescription was ordered from. It matches data.resource_id on that note’s charting.* events, so key on it to tie the prescription to the note. It is omitted, never null, when the prescription was not ordered from a charting note.

Gotchas

  • Signature and delivery are the standard contract. Verify every delivery per Events (Standard Webhooks, whsec_ secret); dedupe on the envelope id; expect at-least-once with no ordering guarantee.
  • No payment state on the four 1.0 events. They carry no paid/invoiced field. prescription.invoiced and prescription.paid arrive only on a 2.0 subscription; the payment itself is read from the billing events or GET /v0.1/subscriptions / GET /v0.1/invoices.
  • No cancellation reason field. prescription.cancelled sets status to cancelled and timestamps.cancelled_at; it does not carry a structured reason in the versioned contract.
  • data.context is free-form. Treat it as opaque; its keys are not versioned and may change without an eventVersion bump.
  • patient_ref is not guaranteed to be a /v0.1 id. It is an opaque patient reference. Key on emr_patient_id when the event carries it.
  • prescribed_product.code is not a /v0.1 id. It is a product code, not a /v0.1 product or price id.
  • No event signals a declined prescription. No prescription event, lifecycle or billing, says a clinician chose not to prescribe, so do not wait for one; handle that case on your own clock (see Order exceptions).

Correlating to your patient

data.emr_patient_id is the patient’s /v0.1 id, the id that GET /v0.1/patients/{id} takes. When the event carries it, join the event to your patient on it. It is set whenever the id is known and omitted otherwise, never null. data.patient_ref is an opaque OpenLoop reference, not guaranteed to be the /v0.1 patient id you create with POST /v0.1/patients, and the event carries no email or phone to join on. When the event has no emr_patient_id, how your tenant maps patient_ref to your own records is agreed with your implementation contact when your endpoint is registered. The claim that a /v0.1 patient read carries no such reference is locked by check v01-patient-read-carries-only-partner-ids on Order status and tracking (Recipe 4.4); this page has no runner-checkable behaviour of its own.

Order status and tracking

How to use these events: set-up, rendering status, dedupe and correlation

Events

The envelope, the Standard Webhooks signature, and the delivery policy

Order exceptions

Cancellations and orders that have gone quiet