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 firstprescription.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 JSONPOST, 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
2xxquickly 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 at1.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.- Key on
data.resource_id. It is the stable surrogate id of the prescription. - Drop repeats on the envelope
id. Delivery is at-least-once, so the same event can arrive more than once; ignore anidyou have already applied. (idis also thewebhook-idheader.) - Keep the latest by
occurredAt. Deliveries are not ordered, so if an event’soccurredAtis older than the one you already applied for thatresource_id, record it but do not let it overwrite the status you show.
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_idis your/v0.1patient id, theidthatGET /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, nevernull.data.patient_refis an opaque reference, not guaranteed to be the/v0.1patient id, and the event carries no email and no phone. A patient you created withPOST /v0.1/patientscomes back fromGET /v0.1/patients/{id}with no matching reference on it, so when the event has noemr_patient_id, how your tenant correlates it to a patient is agreed with your implementation contact when the endpoint is registered.data.prescribed_product.codeis a product code, not a/v0.1product id or price id. Do not join it to your catalogue.- Nothing on the event points back at your intake. It carries no
encounter_idand 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 samedata shape. The full field list, with types and nullability, is on
Prescription events. The ones this page uses:
Gotchas
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.
Related
Prescription events
The reference: every
data field, its type, the status enum and the timestampsEvents
The envelope, the Standard Webhooks signature, and the delivery policy
Order exceptions
When this stage goes wrong: cancelled, or gone quiet

