Skip to main content
Webhook delivery is configured per customer; there is no self-serve subscription endpoint. Your OpenLoop implementation contact registers your HTTPS endpoint, selects the event types it receives, and returns the signing secret once. Until your endpoint is registered this page is the contract to build against, not a step you can complete yourself.
When delivery is enabled for your organization, OpenLoop POSTs state changes to your endpoint as signed webhooks — past-tense facts you react to instead of polling. Every event — clinical, lab, document, scheduling, prescription or billing — rides the same envelope, the same Standard Webhooks signature, and the same delivery policy; they differ only by 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

The POST 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. Each POST carries: Each delivery also carries user-agent: OpenLoop-Webhooks/1.0 and accept-encoding: identity. Verifying by hand:
  1. Concatenate <webhook-id>.<webhook-timestamp>.<raw-request-body> — the exact bytes received, before any JSON parsing.
  2. Strip the whsec_ prefix from your signing secret and base64-decode the remainder to get the key.
  3. Compute HMAC-SHA256 over the concatenated string, keyed with the decoded secret.
  4. Base64-encode the result and compare it, with a constant-time comparison, against the v1,-prefixed token in webhook-signature (prefix stripped).
  5. Reject a webhook-timestamp more than 5 minutes from your own clock, so a captured delivery can’t be replayed later.

Telling environments apart

Every delivery, test deliveries included, carries openloop-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:
  1. Read openloop-environment and pick the signing secret you were given for that environment.
  2. 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.
  3. Drop a verified delivery from an environment that URL should not serve, e.g. staging on your production handler, and still answer 2xx so it is not retried.
The values are fixed: 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 a webhook-id you have already applied as a duplicate.
  • Delivery is version-matched. A subscription is pinned to one exact eventVersion and receives only events of that version. Where a type ships at more than one version — e.g. intake.created / intake.completed at 1.0 and 1.1, intake_appointment.* at 2.0, or the prescription billing verbs at 2.0 — subscribe to each version you need; a 1.0 subscription will not receive a 1.1 or 2.0 event. A subscription without a version gets the type’s default version: 1.0 where the type has one.
  • extra_fields is usually a raw passthrough. On most payloads extra_fields is 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_appointment and requested_form_completion carry a defined extra_fields object.
  • Nullable fields can be null on a valid event. A field marked nullable below is present with a null value 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 the data 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.
The four lifecycle verbs are emitted at 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.
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.
Example: lab_result.created
Do not rely on receiving lab_result.created before lab_result.updated. Deliveries are not ordered, and if the delivery that announced the first results is lost, no lab_result.created is sent for that order. Treat a lab_result.updated for a lab_order_ref you have not seen as its first result, and order a lab order’s events by occurredAt.

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.
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.
Deliveries are not ordered: keep the newest state per 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 at 1.0. extra_fields is the source record’s native object (opaque). It emits appointment.created and appointment.updated only: a cancelled or deleted clinical appointment sends no appointment.deleted, so read the cancellation from status on appointment.updated.
  • Scheduling appointments (1.1 / 1.2 / 2.0) — appointments booked through OpenLoop’s scheduling service (your own /v0.1/appointments bookings). It is first-party, so extra_fields is the defined SchedulingAppointmentExtra object (table in the 2.0 tab), not a passthrough. 1.1 omits appointment_type_refs; 1.2 and 2.0 add it as a required field. The scheduling producer emits 2.0, falling back to 1.1 where appointment_type_refs is 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.
The canonical fields are the same across versions, except that 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.deleted carries the status the appointment had when it was deleted, often scheduled. Treat the event type, or extra_fields.deleted_at, as the deletion, not status. A deleted appointment no longer appears in GET /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.
Clinical appointments at 1.0:
At 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 and 1.1 are not two shapes of the same intake: they come from different places.
  • 1.1 is emitted for intakes submitted through this API. If you submit intakes yourself, this is the version that carries them.
  • 1.0 is emitted for intakes completed in OpenLoop’s own care workflow. intake.signed exists only here.
2.0 is subscribable but not emitted today.
A subscription without a version, or to intake.*, resolves to the 1.0 default. It never receives the 1.1 events for intakes you submitted through this API. Ask your OpenLoop contact to subscribe your endpoint to intake.created and intake.completed at 1.1.
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.
There are no answers and no note body in any of them; read the note as described below. Charting is delivered on staging only today; production emission is switched off until OpenLoop enables it, and your subscription is added by your implementation contact.
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).
From a charting event to the note. On 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.
The list holds every completed response on that encounter — your intake and the note. The note is the row whose 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.
The producer emits only 2.0 today — subscribing to the 1.0 default receives nothing.
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.
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:
extra_fields is a free-form provider passthrough (raw provider fields with no fixed schema), not part of the versioned contract.
Example: invoice.paid
Amounts are in the currency’s smallest unit (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.
extra_fields is a free-form provider passthrough (raw provider fields with no fixed schema), not part of the versioned contract.
The 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.
On 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.
Every timestamp is an ISO-8601 string; the REST API returns epoch seconds under the same names.

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.
A dispute carries no customer, so 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.
Every timestamp is an ISO-8601 string; the REST API returns epoch seconds under the same names.

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.

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_id and provider_invoice_id on the invoice and subscription events are the same ids returned by GET /v0.1/subscriptions and GET /v0.1/invoices. Join on them to attach a payment event to the subscription or invoice you already hold. provider_invoice_id on a credit note event is the refunded invoice, provider_payment_intent_id on a dispute event leads to the disputed payment, and provider_checkout_session_id on a checkout session event is the id POST /v0.1/checkouts/sessions returned.
  • Your patient id — emr_patient_id, when an event carries it, is the patient’s /v0.1 id, the id that GET /v0.1/patients/{id} takes. Prescription, patient-document, intake, charting and requested-form-completion events carry it, as does the 1.0 clinical appointment event, whenever the producer knows the id; it is omitted otherwise and never null. 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_ref is 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_id on lab_order.* and lab_order_ref on lab_result.* are the order_id that POST /v0.1/laboratories returned. 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_ref on lab events is always null today.
  • Intake and charting — encounter_id on intake.* and charting.* is the Partner API encounter id, the same value your completed submit returned, so key those events by it. patient_ref on them is not guaranteed to be your /v0.1 patient id. Do not assume it is.
  • Form requests — intake_id on requested_form_completion.* is the resource_id of the requested form’s intake.* (at 1.0) or charting.* events, and both carry the same questionnaire_ref; join the request to the form by it.
  • Prescriptions — charting_note_id on prescription.* is the charting note the prescription was ordered from: the resource_id of that note’s charting.* events. Key prescriptions to the note by it; it is omitted when the prescription was not ordered from a charting note.