Skip to main content
By the end of this page you will be able to show a patient where their order is: whether the pharmacy has it, and the carrier tracking id once it ships. All of that reaches you as signed prescription webhook events that OpenLoop POSTs to an endpoint you run. There is no order read to call.

What you’ll do

1

Give OpenLoop an HTTPS endpoint

Status arrives as prescription webhook events. You send the endpoint URL to your implementation contact, who registers it and returns the signing secret; there is no self-serve registration.
2

Verify every delivery

Check the Standard Webhooks signature before trusting a payload — see Events.
3

Render status from the payload

data.status for the lifecycle stage, data.timestamps.* for the trail, data.tracking_ref and data.carrier for tracking.
4

Store the order, not the event

Key on data.resource_id, drop repeats on the envelope id, and keep the latest state by occurredAt.
5

Settle correlation before you build

Key the patient on data.emr_patient_id, your /v0.1 patient id, when the event carries it. For events without it, agree how the opaque data.patient_ref maps to your patients (Recipe 4.4).

Why events, not a read

There is no partner order read; order status and tracking arrive only as prescription webhook events. Nothing you call creates an order — an order is raised upstream, and the first prescription.created event for it is the first time there is anything to show the patient. Paying and submitting an intake come before that and have their own confirmations; see Payments and checkout and Questionnaire workflow. These are signed webhooks delivered by the same pipeline as every OpenLoop event: one envelope, one signature scheme, one delivery policy, all documented in Events.

Recipe 4.1 · Give OpenLoop your endpoint

Stand up an HTTPS endpoint that accepts a JSON POST, and send its URL to your implementation contact. They register it, select the prescription.* events, and return your signing secret once. Build the handler so that it:
  • verifies the Standard Webhooks signature before trusting the body (see Events);
  • returns a 2xx quickly and does its work afterwards;
  • tolerates the same event arriving twice (Recipe 4.3);
  • tolerates events arriving out of order (Recipe 4.3).

Recipe 4.2 · Read the lifecycle and render status

Four prescription lifecycle events are delivered at 1.0, each carrying the order’s current state. They differ by data.status and which data.timestamps.* field they set: prescription.cancelled is not a step every order passes through. Order exceptions covers it and orders that have gone quiet.
prescription.shipped (synthetic)

Render from data.status

Every event carries the prescription’s current data.status. One way to turn it into a single patient-facing line — the wording is yours:
Payment state is not on these events. There is no paid/on-hold/refund status on a prescription event. Payment problems surface through the billing events and the payment flow — see Payment failure and Payments and checkout.

Tracking

data.tracking_ref is the tracking number and data.carrier the carrier name. They are typically set on prescription.shipped, but the contract does not pin them to that event, so render “shipped, tracking to follow” when tracking_ref is empty. data.timestamps.shipped_at is a UTC ISO-8601 timestamp — show it as a datetime; it is a ship event, not a delivery estimate.

Recipe 4.3 · Store the order: dedupe, order, accumulate

One order produces several events, and one prescription can have more than one order. Store one record per prescription and update it from each event.
  1. Key on data.resource_id. It is the stable surrogate id of the prescription.
  2. Drop repeats on the envelope id. Delivery is at-least-once, so the same event can arrive more than once; ignore an id you have already applied. (id is also the webhook-id header.)
  3. Keep the latest by occurredAt. Deliveries are not ordered, so if an event’s occurredAt is older than the one you already applied for that resource_id, record it but do not let it overwrite the status you show.
The timestamps accumulate per order. Each data.timestamps.* field is absent until its stage happens, and from then on it is populated on every later event for that order: timestamps.ordered_at set on a prescription.shipped event means the order was placed, even if you never received prescription.ordered. A later order on the same prescription carries only its own timestamps, so a second order’s prescription.cancelled can arrive with no ordered_at or shipped_at after the first order shipped. Merge each event’s timestamps into the record, keeping the first value set for each timestamp so a later order never overwrites it, and draw the progress trail from the merged timestamps. A prescription.cancelled with neither ordered_at nor shipped_at usually means that order was never placed: if the prescription already shipped, that shipment still stands, so don’t downgrade the status you show from shipped to cancelled on it. Events can arrive out of order, so a prescription.ordered or prescription.shipped that arrives after a cancel wins over it. An order with more than one fill sends each event once per fill, which the merge absorbs. Keep carrier and tracking_ref from the order’s first shipped event, since they don’t change after it, but take pharmacy from the latest event, since it changes when an order is rerouted.

Recipe 4.4 · Match the event to your patient

Settle this before you build, because the event does not always carry the identifiers you hold.
  • data.emr_patient_id is your /v0.1 patient id, the id that GET /v0.1/patients/{id} takes, when the event carries it. Key the event to your patient on it. It is omitted when the id isn’t known, never null.
  • data.patient_ref is an opaque reference, not guaranteed to be the /v0.1 patient id, and the event carries no email and no phone. A patient you created with POST /v0.1/patients comes back from GET /v0.1/patients/{id} with no matching reference on it, so when the event has no emr_patient_id, how your tenant correlates it to a patient is agreed with your implementation contact when the endpoint is registered.
  • data.prescribed_product.code is a product code, not a /v0.1 product id or price id. Do not join it to your catalogue.
  • Nothing on the event points back at your intake. It carries no encounter_id and no questionnaire response id.
That a /v0.1 patient read carries no patient_ref is locked by check v01-patient-read-carries-only-partner-ids.

What comes back

Every event carries the same data shape. The full field list, with types and nullability, is on Prescription events. The ones this page uses:

Gotchas

Do not build an order-polling loop. There is no order read on the partner surface. Anything you show about an order after it is raised comes from the events you have stored.
Do not treat data.patient_ref as your patient id. It is an opaque reference. Key on data.emr_patient_id when the event carries it; matching patient_ref to a /v0.1 patient is agreed when the endpoint is registered.
Verify the signature. Treat an unsigned or unverifiable POST as hostile — see Events for the Standard Webhooks verification steps.
Webhook events cannot be exercised by the conformance runner. The envelope, signature and delivery policy are the deployed contract (see Events); delivery to your endpoint is configured per customer by your implementation contact.

Prescription events

The reference: every data field, its type, the status enum and the timestamps

Events

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

Order exceptions

When this stage goes wrong: cancelled, or gone quiet