type and the shape of data.
Verify each webhook’s signature before trusting it, return a 2xx quickly, and do slower work
asynchronously.
The envelope
ThePOST body is exactly these five top-level keys:
Example: prescription.shipped
Event types
These are the event types delivered today. An endpoint receives only the types your OpenLoop contact subscribes it to; a subscription may be an exact type (prescription.shipped), a whole family
(prescription.*), or everything (*).
An endpoint is pinned to one eventVersion per type (see Delivery semantics),
so where Emitted today lists more than one version, subscribe to each version you need.
Selections are expanded into concrete types when your endpoint is saved. An endpoint saved with
*
or a family wildcard (lab_order.*) before a type existed does not receive that type until its
subscriptions are updated. Ask your OpenLoop contact to re-save the endpoint when a new type appears
here.prescription.delivered exists in the event vocabulary but is not produced today. Do not build
on it.Lab events are delivered by arrangement. A lab event reaches your endpoint only once OpenLoop has
linked your lab network account to your organization; until then it is not delivered to you. Your
OpenLoop implementation contact confirms when that link is in place.
Payments types are
2.0 only. Every invoice.*, subscription.*, credit_note.*,
dispute.* and checkout.session.* type is delivered at 2.0, the shape documented on this page.
There is no 1.0 payments subscription.Verifying the signature
Deliveries are signed per the Standard Webhooks spec, so off-the-shelf verification libraries work. EachPOST carries:
Each delivery also carries
user-agent: OpenLoop-Webhooks/1.0 and accept-encoding: identity.
Verifying by hand:
- Concatenate
<webhook-id>.<webhook-timestamp>.<raw-request-body>— the exact bytes received, before any JSON parsing. - Strip the
whsec_prefix from your signing secret and base64-decode the remainder to get the key. - Compute
HMAC-SHA256over the concatenated string, keyed with the decoded secret. - Base64-encode the result and compare it, with a constant-time comparison, against the
v1,-prefixed token inwebhook-signature(prefix stripped). - Reject a
webhook-timestampmore than 5 minutes from your own clock, so a captured delivery can’t be replayed later.
Telling environments apart
Every delivery, test deliveries included, carriesopenloop-environment. The body and the
signature are the same in every environment, so this header is the only way to tell a staging
event from a production one when both reach the same URL.
Signing secrets are never shared across environments: an endpoint registered in staging has its own
secret, and it cannot verify a production delivery. If one URL receives more than one environment:
- Read
openloop-environmentand pick the signing secret you were given for that environment. - Verify the signature with it. A delivery whose header was changed in transit fails here, because the secret for the claimed environment did not sign it.
- Drop a verified delivery from an environment that URL should not serve, e.g.
stagingon your production handler, and still answer2xxso it is not retried.
production, staging and development. Treat any other value as an
unknown environment and do not process it.
Delivery semantics
Your endpoint must be
https://, present a valid TLS ≥1.2 certificate, and resolve to a public
address — redirects are not followed and private/loopback targets are refused.
What not to assume
- No delivery-status or replay API. There is no endpoint to query past deliveries, and a failed delivery is not re-sent beyond the retries above (an operator can re-drive it).
- No ordering. Order by
occurredAt, and treat awebhook-idyou have already applied as a duplicate. - Delivery is version-matched. A subscription is pinned to one exact
eventVersionand receives only events of that version. Where atypeships at more than one version — e.g.intake.created/intake.completedat1.0and1.1,intake_appointment.*at2.0, or the prescription billing verbs at2.0— subscribe to each version you need; a1.0subscription will not receive a1.1or2.0event. A subscription without a version gets the type’s default version:1.0where the type has one. extra_fieldsis usually a raw passthrough. On most payloadsextra_fieldsis the source record’s native object and is not part of the versioned canonical contract — build on the canonical fields and treat it as opaque. The exceptions are documented per type below: the scheduling appointment versions (1.1/1.2/2.0),intake_appointmentandrequested_form_completioncarry a definedextra_fieldsobject.- Nullable fields can be
nullon a valid event. A field marked nullable below is present with anullvalue when the source has nothing to put there; an absent key is not expected. - No self-service registration. Your endpoint and signing secret are configured by your OpenLoop implementation contact.
Event payloads
Each table below is thedata object for that event type (the envelope keys id / type /
eventVersion / occurredAt are above). Event types that share a data shape are documented once;
the intro says what each verb sets. Every field is reproduced from the delivered schema.
Required means the key is always present; a Nullable key may carry null.
Prescriptions
prescription.created fires when a prescription is created, prescription.ordered when it is sent to
the pharmacy, prescription.shipped when it ships (carrier/tracking typically present), and
prescription.cancelled when it is cancelled. prescription.invoiced, prescription.paid,
prescription.refund_requested and prescription.changed follow the prescription’s billing.
The eight come from the same producer but form two groups with different shapes. The four lifecycle
verbs are emitted at 1.0 and carry the 1.0 shape; the four billing verbs are emitted at 2.0 and
carry the 2.0 shape. The two shapes differ in patient_ref nullability, context and the
timestamps keys (see the tabs below). Within a group, the events share one shape and differ only
in status and which timestamps.* field the event sets.
Lifecycle, 1.0
Billing,
2.0
timestamps.* accumulate per order within a group: once a stage’s timestamp is set for an order, it
stays populated on every later event for that order, so a missed event loses none of that order’s
stages. One prescription (resource_id) can have more than one order, and each order’s events carry
only that order’s timestamps. For example, a second order that is created and cancelled after the
first one shipped sends a prescription.cancelled with no ordered_at or shipped_at. To show a
prescription’s progress, merge the timestamps of every event you received for its resource_id,
keeping the first value set for each timestamp, rather than reading only the latest event. A
prescription.cancelled with neither ordered_at nor shipped_at usually means that order was
never placed: when the prescription already shipped, that shipment still stands, so don’t show the
prescription as cancelled on it. Events can also 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. carrier and tracking_ref are set by an order’s first shipped
event and don’t change after it; pharmacy can change when an order is rerouted, so take it from
the latest event. A 1.0 event has no billing timestamps; those arrive only on the 2.0 billing
events.- 1.0 (default)
- 2.0
1.0 only; subscribing to them at 2.0 receives nothing
today. The four billing verbs exist only at 2.0. To follow a prescription end to end, subscribe
to the lifecycle verbs at 1.0 and the billing verbs at 2.0.
Linking a prescription to its 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 on every prescription event, 1.0 and 2.0, when OpenLoop has the value, and
omitted, never null, when the prescription was not ordered from a charting note.
Lab orders and results
lab_order.created fires once, when a lab order is placed, and lab_order.updated fires on every
later transition at the lab network, whether or not status changes. lab_result.created fires on the first transition that makes results
available for an order, and lab_result.updated on each later one, including when partial results
become final. One transition can produce both a lab_order.updated and a lab_result.* event.
Both families carry references and status only. No result values, analyte names, codes,
reference ranges, interpretations, documents or patient demographics ride on these events. They
tell you that something happened to an order; they do not deliver its results.
Only 1.0 exists for each type. Lab events are delivered by arrangement: they reach your endpoint
only once OpenLoop has linked your lab network account to your organization.
Lab orders
lab_order.created and lab_order.updated carry the same data shape. Branch on status, not on
the event type: lab_order.created is sent only at the first status, and every later transition,
including cancellation and completion, arrives as lab_order.updated. status can repeat: two
received.* transitions send two lab_order.updated events, both with status: received, and
vendor_status tells them apart.
- 1.0 (default)
status: completed means the lab finished processing the order. Results may still be in flight on
OpenLoop’s side when the event arrives.Example: lab_order.created
Lab results
lab_result.created and lab_result.updated carry the same data shape. A transition that does
not change result availability, such as a shipping update after results exist, sends no
lab_result.* event.
Partial results are sent only when they are enabled for your lab account. Without them, an order
produces one
lab_result.created with status: final.
- 1.0 (default)
Example: lab_result.created
Patients
patient.created fires when a patient record is created and patient.updated when one
changes; both deliver the patient’s canonical demographic snapshot. These fields are PHI — handle
accordingly.
patient.created and patient.updated carry the same data shape.
- 1.0 (default)
extra_fields is the source record’s native payload; its shape varies and is not covered by
eventVersion.
patient.updated carries the full snapshot after the change, not a diff. Compare it to the record
you hold to see what changed.
Patient documents
patient_document.created fires when a document is added to a patient’s record and
patient_document.updated when its details change, e.g. its title. Both carry the document’s
metadata only: never the file, a link to it, or its contents. resource_id is not a
/v0.1/document-references id, so the document endpoints of this API do not return it.
patient_document.created and patient_document.updated carry the same data shape. Only 1.0
exists.
- 1.0 (default)
resource_id. Order the events by the
envelope’s occurredAt, not by updated_at: updated_at does not move on a visibility change, so
two events can share it and differ in visible_to_patient, and its local offset does not sort as a
string. occurredAt has one-second precision, so two events in the same second can still tie.
Treat every
patient_document.* event as PHI: patient_ref ties the document to a patient, and
title can name a condition or a test.Appointments
appointment.created fires when an appointment is created, appointment.updated when it changes
(reschedule, status change), and appointment.deleted when it is cancelled / deleted; each delivers
the canonical appointment snapshot.
Appointments come from two producers — subscribe to the versions you need:
- Clinical appointments (
1.0) — appointments created by OpenLoop’s care workflow, emitted at1.0.extra_fieldsis the source record’s native object (opaque). It emitsappointment.createdandappointment.updatedonly: a cancelled or deleted clinical appointment sends noappointment.deleted, so read the cancellation fromstatusonappointment.updated. - Scheduling appointments (
1.1/1.2/2.0) — appointments booked through OpenLoop’s scheduling service (your own/v0.1/appointmentsbookings). It is first-party, soextra_fieldsis the definedSchedulingAppointmentExtraobject (table in the2.0tab), not a passthrough.1.1omitsappointment_type_refs;1.2and2.0add it as a required field. The scheduling producer emits2.0, falling back to1.1whereappointment_type_refsis unavailable.
appointment.created, appointment.updated and appointment.deleted carry the same canonical data
shape. The versions differ in extra_fields; 1.0 can also carry emr_patient_id, and 2.0 adds
provider_name and video_meeting_url.
- 1.0 (default)
- 1.1
- 1.2
- 2.0
1.0 can carry emr_patient_id
and 2.0 adds provider_name and video_meeting_url; otherwise the producers differ only in
extra_fields. At 1.0, extra_fields is the source record’s native object, not covered by
eventVersion — treat it as opaque. At 1.1 / 1.2 / 2.0
extra_fields is the structured SchedulingAppointmentExtra above — 1.1 without
appointment_type_refs, 1.2 and 2.0 with it.
Matching an event’s status to an appointment read
GET /v0.1/appointments and the scheduling events (1.1 / 1.2 / 2.0) describe the same state in
different words. The read has a status of open or closed, with an outcome once it closes.
The event has one canonical data.status:
Two cases where the read and the latest event differ:
- Deleted appointments.
appointment.deletedcarries the status the appointment had when it was deleted, oftenscheduled. Treat the event type, orextra_fields.deleted_at, as the deletion, notstatus. A deleted appointment no longer appears inGET /v0.1/appointments. - Unresolved appointments. When a reopened appointment finds no clinician for its window, it
stays closed with outcome
unresolved, and no event is sent for that change. The read is the only place it shows.
1.0:
1.0, appointment.updated carries the full snapshot after the change and no list of what
changed. Compare it to the appointment you hold.
Intake
intake.created fires when a patient’s intake (questionnaire response) is created, intake.signed
when it is signed, and intake.completed when it is completed (finished / locked). intake.completed
sets canonical status to completed; intake.signed populates
extra_fields.formAnswerGroup.form_answer_group_signings at 1.0.
intake.created, intake.signed and intake.completed carry the same data shape.
- 1.0 (default)
- 1.1
- 2.0
1.0 and 1.1 are not two shapes of the same intake: they come from different places.
1.1is emitted for intakes submitted through this API. If you submit intakes yourself, this is the version that carries them.1.0is emitted for intakes completed in OpenLoop’s own care workflow.intake.signedexists only here.
2.0 is subscribable but not emitted today.
intake.signed and intake.completed for the same form share resource_id, and a signed form is
not always completed. Tell them apart by type, not by status: deduping on resource_id alone
drops one of them.
extra_fields is the source record’s native payload; its shape varies and is not covered by
eventVersion.
Intake payloads carry PHI, so handle them with the same care as patient data. At
1.1 that includes
the answer tree in extra_fields; 1.0 carries no answers, but its patient references are still
PHI.Charting
charting.created, charting.signed and charting.completed fire for a clinician’s charting
form — any clinical form that is not one of the intake forms — when it is created, signed, and
completed (finished / locked). They share the intake shape minus program, intake_kind,
concept_ids and eligibility. Today they carry metadata only: no answers, no note body.
The three types carry the same data shape. Only 1.0 exists, so a default subscription and a
wildcard both receive what is emitted. Selections are expanded when the endpoint is saved: an
endpoint registered with * before these types existed does not receive them until its
subscriptions are updated, and intake.* never covers them; add charting.* or the three types.
- 1.0 (default)
Key on
data.encounter_id. A note that OpenLoop’s charting workflow writes is stamped with the
encounter your completed intake created, and the event carries that id as data.encounter_id. It is
the same encounter_id your intake submit returned, so you can match the event to your own record
before you read anything. The note itself reaches the partner surface as a questionnaire response on
that encounter (the encounter filter was verified on staging 2026-10-19).charting.completed only, list the completed responses
on the event’s encounter. charting.created and charting.signed arrive while the form is still
in_progress (a signed form is not yet locked), so the read below returns nothing for them.
questionnaire_canonical ends in /<questionnaire_ref> (the event’s
questionnaire_ref; match the tail, the prefix is the form’s URL and is not a contract); if
several match, take the newest updated_at. Its answers carry the note text. Such rows omit
questionnaire_id, so do not filter by one. Match on canonical and encounter, not on list position.
The event and the row are written by different steps, so if the row is not listed yet, retry with
backoff; do not compare updated_at to occurredAt.
The cookbook page Encounter notes walks through the subscription,
the event and the read with samples.
When data.encounter_id is null, the form was started outside the charting workflow and is
written against the patient only, so find it through the patient: data.emr_patient_id, when the
event carries it, is the /v0.1 patient id, and
GET /v0.1/questionnaire-responses?subject=Patient/<data.emr_patient_id>&status=completed lists the
form. The key is omitted when the id isn’t known, never null; without it, patient_ref is not
guaranteed to be a /v0.1 patient id, so how your tenant maps it to a patient is agreed with your
implementation contact when the endpoint is registered. See
Correlating events to your records.
Intake appointments
intake_appointment.created fires when an intake form is first linked to an appointment and
intake_appointment.updated when that link changes.
intake_appointment.created and intake_appointment.updated carry the same data shape.
- 1.0 (default)
- 2.0
extra_fields here is not a passthrough; it carries only changed_fields (the names of fields
that changed).
Requested form completions
requested_form_completion.created fires when a patient is sent a request to fill out a form,
requested_form_completion.updated when the request’s status changes, and
requested_form_completion.deleted when the request is deleted. These events report the
request, not the submitted form: the submitted form is the resource intake.* and charting.*
describe (see Intake and Charting), and intake_id points at it.
The three types carry the same data shape. Only 1.0 exists, so a default subscription and a
wildcard both receive what is emitted. Selections are expanded when the endpoint is saved: an
endpoint registered with * before these types existed does not receive them until its
subscriptions are updated, and intake.* and charting.* never cover them; add
requested_form_completion.* or the three types.
- 1.0 (default)
The set is fixed for
1.0: a new value would come with a new eventVersion. A request’s
completed means the patient submitted the form, not that the form is locked: the form’s own
intake.* / charting.* events carry its status, and intake.completed / charting.completed
fire only when the form is locked.
requested_form_completion.updated fires only when status changes: when the patient first opens
the form (in_progress) and when they submit it (completed). Saving a draft sends no .updated.
A submit is usually followed shortly by the intake.created (at 1.0) event for an intake form,
or the charting.created event for any other form (see Charting),
whose resource_id is this event’s intake_id. That event is not guaranteed for every
organization, and deliveries are not ordered, so either can arrive first: do not wait for it before
acting on a request’s completed.
requested_form_completion.deleted keeps resource_id and resource_organization_id. Every other
reference and extra_fields.item_type are null, status is unknown, and emr_patient_id is
absent. Route on the event type, not on status.
Dedupe on the envelope id, as for every event. Delivery is at least once and not ordered, and
nothing in data orders two events for the same resource_id: there is no created_at or
updated_at, and unlike intake and charting there is no organization object.
Treat every
requested_form_completion.* event as PHI: patient_ref ties the request to a patient.
The events carry references, status and the two extra_fields keys only: no form name, no
answers, and no names or contact details for the patient or provider.Invoice
invoice.paid fires when an invoice is paid in full — status is paid and paid_date is
populated. This is the event to key settlement on; it carries the canonical invoice snapshot (amounts,
status, line items, billing customer) at the moment payment completed.
invoice.created, invoice.finalized, invoice.payment_succeeded, invoice.payment_failed,
invoice.payment_action_required, invoice.paid, invoice.voided and invoice.marked_uncollectible
carry the same data shape. Each is a snapshot of the invoice when the event occurred; read status and
the timestamps from the payload, not from the event name alone:
- 2.0
extra_fields is a free-form provider passthrough (raw provider fields with no fixed schema), not
part of the versioned contract.
Example: invoice.paid
19900 is $199.00), and timestamps are ISO-8601
strings.
Subscription
subscription.created fires when a subscription is created and subscription.updated when it changes
(status, items, schedule). On subscription.created the previous object is absent; on
subscription.updated, changed_fields names what changed and previous holds the prior values.
subscription.canceled fires when a subscription is canceled and ends: status is canceled, and
canceled_at and ended_at are set. subscription.paused and subscription.resumed fire when the
subscription’s status changes to and from paused. subscription.trial_will_end fires three days
before trial_end, or at once when a trial is ended early.
A pause made with
POST /v0.1/subscriptions/{provider_subscription_id}/pauses pauses payment
collection; it does not change status. It arrives as subscription.updated, with paused set to
true and resumes_at set to the resume date when one was given, and never as subscription.paused
or subscription.resumed. To track those pauses, listen to subscription.updated.subscription.created, subscription.updated, subscription.canceled, subscription.paused,
subscription.resumed and subscription.trial_will_end carry the same data shape.
- 2.0
extra_fields is a free-form provider passthrough (raw provider fields with no fixed schema), not
part of the versioned contract.
subscription.updated example is a cancellation scheduled for the end of the period:
status is still active, and changed_fields and previous show what moved.
Credit note
credit_note.created fires when a credit note is created and credit_note.voided when one is voided
(status is void). A refund issued with POST /v0.1/invoices/{provider_invoice_id}/refunds creates
a credit note, and the credit note fields below mirror that endpoint’s response.
Listen to
credit_note.* for refunds. Refunds are published as credit_note.created and
credit_note.voided at 2.0. refund.* is not published at 2.0; do not subscribe to it for
refunds.credit_note.created, changed_fields is [] and previous is absent. On credit_note.voided,
changed_fields names what changed (e.g. ["status"]) and previous holds the prior values (e.g.
{ "status": "issued" }), or changed_fields is [] when the event is a snapshot with no recorded
change. Read status rather than relying on previous.
credit_note.created and credit_note.voided carry the same data shape.
- 2.0
Dispute
dispute.created fires when a customer disputes a charge, dispute.updated when a dispute changes
(for example, evidence is submitted), dispute.funds_withdrawn when the disputed funds are withdrawn,
dispute.funds_reinstated when they are returned, and dispute.closed when the dispute ends. On
dispute.closed, status gives the result: won, lost or warning_closed.
Dispute evidence is not in the event. The evidence holds the customer’s personal data, so it is
never published.
evidence_details (the deadline and submission state) is included.billing_customer.provider_customer_id and
billing_customer.email are always null. To find the customer, read the payment intent with
GET /v0.1/intents/payments/{provider_payment_intent_id}.
On dispute.created, changed_fields is [] and previous is absent. On the other dispute types,
changed_fields names what changed (e.g. ["status"]) and previous holds the prior values, or
changed_fields is [] when the event is a snapshot with no recorded change.
dispute.created, dispute.updated, dispute.funds_withdrawn, dispute.funds_reinstated and
dispute.closed carry the same data shape.
- 2.0
Checkout session
checkout.session.completed fires when a customer completes a checkout session and
checkout.session.expired when a session expires before it completes. For a payment method that
settles later, checkout.session.completed arrives with payment_status unpaid, then
checkout.session.async_payment_succeeded or checkout.session.async_payment_failed reports the
result.
provider_checkout_session_id is the id that POST /v0.1/checkouts/sessions returns. The event
describes the session’s outcome only: it never carries the session’s secrets or its payable link, and
it carries no customer details except billing_customer.email.
Every checkout session event is a snapshot: changed_fields is always [] and previous is absent.
An unrecognized type, status or payment_status is sent as unknown.
checkout.session.completed, checkout.session.expired, checkout.session.async_payment_succeeded
and checkout.session.async_payment_failed carry the same data shape.
- 2.0
Correlating events to your records
Events carry OpenLoop’s opaque references, not your own ids. Resolve them against the synchronous read APIs and a mapping you keep at link time:- Billing —
billing_customer.provider_customer_id,provider_subscription_idandprovider_invoice_idon the invoice and subscription events are the same ids returned byGET /v0.1/subscriptionsandGET /v0.1/invoices. Join on them to attach a payment event to the subscription or invoice you already hold.provider_invoice_idon a credit note event is the refunded invoice,provider_payment_intent_idon a dispute event leads to the disputed payment, andprovider_checkout_session_idon a checkout session event is the idPOST /v0.1/checkouts/sessionsreturned. - Your patient id —
emr_patient_id, when an event carries it, is the patient’s/v0.1id, theidthatGET /v0.1/patients/{id}takes. Prescription, patient-document, intake, charting and requested-form-completion events carry it, as does the1.0clinical appointment event, whenever the producer knows the id; it is omitted otherwise and nevernull. When it is present, key the event to the patient by it. When it is absent, fall back to the keys below. - Patients and orders —
patient_refis an opaque surrogate, not your patient id. Map it to your record once when the patient is linked and store the mapping; see Order status and tracking. - Labs —
resource_idonlab_order.*andlab_order_refonlab_result.*are theorder_idthatPOST /v0.1/laboratoriesreturned. Store it when you place the order and key both families on it. This only helps once your lab network account is linked to your organization: until then no lab event is delivered to you.patient_refon lab events is alwaysnulltoday. - Intake and charting —
encounter_idonintake.*andcharting.*is the Partner API encounter id, the same value your completed submit returned, so key those events by it.patient_refon them is not guaranteed to be your/v0.1patient id. Do not assume it is. - Form requests —
intake_idonrequested_form_completion.*is theresource_idof the requested form’sintake.*(at1.0) orcharting.*events, and both carry the samequestionnaire_ref; join the request to the form by it. - Prescriptions —
charting_note_idonprescription.*is the charting note the prescription was ordered from: theresource_idof that note’scharting.*events. Key prescriptions to the note by it; it is omitted when the prescription was not ordered from a charting note.

