Webhook Events
RxScale sends webhooks for the following event types:HTTP Headers
Webhook requests include the following HTTP headers:
If you configured a custom header when creating the subscription, it will also be included. Test webhooks are not signed and carry the header
X-Webhook-Test: true instead.
pharmacy_order_created
Sent when a new pharmacy order is created and assigned to your pharmacy.A pharmacy order is created per fulfillment, not per shop order. One shop order can therefore produce several pharmacy orders over time — for example when it is split into several fulfillments or a fulfillment is added later. These pharmacy orders share
data.order.uid. Use data.uid as the key for a pharmacy order; shop_order_name is not unique. See Pharmacy Orders for details.Pharmacy orders are created for over-the-counter (OTC) purchases too, not only for prescription-based orders — any fulfillment routed to your pharmacy triggers this event, whether or not it includes a prescription. For an OTC-only order,
data.doctor_data and data.prescription_file are null, and data.prepaid is 0.data.shipments is always present. On create it is an empty array — pharmacies have not shipped yet. After the pharmacy adds parcels (Pharmacy Portal, or complete_order with tracking_links), later pharmacy_order_updated deliveries include those shipments.waiting for pharmacy. The payload shows the order as it is when the delivery is sent, so a pharmacy_order_created delivery can already carry a later status.
Possible status values: waiting for pharmacy, pending review, on-hold, in-progress, ready_for_pickup, completed, cancelled
Payload Example
Field Reference
shipping_costs_amount and unpaid_shipping_costs_amount are different fields — the 0-never-null guarantee applies only to the first.data.order.shipping_costs_amount is always an integer: 0 when no shipping is charged, never null.unpaid_shipping_costs_amount is a separate, internal shipping-cost override that is nullable and is not part of the documented webhook contract. If you see it in a payload, do not apply the shipping_costs_amount guarantee to it: it may be absent or null, and null there does not mean “no shipping costs”. Use shipping_costs_amount for shipping reconciliation, and handle unpaid_shipping_costs_amount as an optional, possibly-null value if you read it at all.pharmacy_order_updated
Sent when an existing pharmacy order changes:- Status changes — made in the Pharmacy Portal (including bulk updates), through the External Pharmacy API (including your own
PATCH .../statusandcomplete_ordercalls), or by the automatic status check against your pharmacy system (for example when it reports the order as shipped, completed, or cancelled). - Cancellations — whether the order is cancelled by your pharmacy, by the admin team, or by the automatic status check.
- Shipments — when a shipment is entered manually in the Pharmacy Portal, when a carrier label is booked, or when you complete the order through the External Pharmacy API with
tracking_links. Booking a label sendspharmacy_order_updatedwith that shipment’s tracking number and URL, including when the order is alreadycompleted(see Shipments). - Clarifications — when your pharmacy or the admin team opens a clarification request on the order, which puts it on hold.
- Priority or delivery type — when your pharmacy changes the order’s priority or delivery type in the Pharmacy Portal.
pharmacy_order_created and always carries the full current state of the order, not only the part that changed. The status field reflects the current status, and data.shipments lists every shipment currently on the order (not only the one just added). To find out what changed, compare the payload with the state you stored — see Processing Events Idempotently.
There is no separate pharmacy_order_shipment_created event. Subscribe to pharmacy_order_updated and read data.shipments.
Payload Example
Shipments
data.shipments is the list of parcels the pharmacy has recorded on this order. Use it to pick up tracking details when a pharmacy ships — including split shipments (more than one parcel).
When the array is filled
- Completing the order via
PATCH /v1/external_pharmacy_api/pharmacy_orders/{uid}/complete_orderwithtracking_linkscreates a shipment and then sendspharmacy_order_updated. - Adding a shipment in the Pharmacy Portal sends
pharmacy_order_updated. That covers a manual tracking link and a booked carrier label. If the order is alreadycompleted, you receive anotherpharmacy_order_updatedwithstatus: completedand the shipment ondata.shipments, includingtracking_numberandtracking_url. The payload includes all current shipments, ordered bysequence_number. pharmacy_order_createdalmost always has"shipments": []. Do not treat a missing tracking URL on create as an error.
- Treat
uidas the stable identity of a parcel. A laterpharmacy_order_updatedmay add further entries; existing UIDs stay the same. - Prefer
tracking_urlfor customer-facing tracking.tracking_numberandcarrier_nameare present when the pharmacy or carrier supplied them; either can benullon a newly created placeholder shipment. is_testistrueonly when the parcel was booked against a carrier sandbox (no real dispatch). Ignore test shipments for live fulfillment.- A cancelled parcel stays in the array. Its
tracking_numberandtracking_urlarenull, because that parcel is no longer in transit. return_tracking_numberandreturn_label_expiry(YYYY-MM-DD) are set only after a return label is issued; otherwise they arenull.
Internal label-file locations are not included in the webhook. Use
tracking_url / tracking_number for tracking, not storage paths.Organisation-Level Webhooks
When the webhook subscription was created via the Management API (organisation-level), order events differ as follows:- The
skuobjects insideorder_itemsandfulfillment.itemsare enriched with Shopify identifiers (shop_variation_id,shop_product_external_id). - A
fulfillmentobject is added with fulfillment order details. prescription_fileis not included.
The
fulfillment field and the Shopify identifiers (shop_variation_id, shop_product_external_id) inside sku objects are only present in organisation-level webhook deliveries. Pharmacy-level webhooks do not include these fields.pharmacy_sku_stock_updated
Sent when a pharmacy SKU’s stock level changes. This includes:- Direct stock updates via the Pharmacy API (
PATCH /v1/.../pharmacy_skus/{uid}/stockor inventory endpoints). - Automatic stock reduction when a pharmacy order is completed. This fires for both manual completion (via the pharmacy UI / API) and automatic completion when RxScale detects the order has reached a shipped or completed state via its status-check integration with the pharmacy’s backend. One event is emitted per pharmacy SKU on the completed order.
Payload Example
Field Reference
Organisation-Level Webhooks
When the webhook subscription was created via the Management API (organisation-level), stock events include additional data:- The
skuobject is enriched with Shopify identifiers (shop_variation_id,shop_product_external_id). - A
shop_identifierfield is added at thedatalevel.
The
shop_identifier field and the Shopify identifiers (shop_variation_id, shop_product_external_id) inside the sku object are only present in organisation-level webhook deliveries. Pharmacy-level webhooks do not include these fields.appointment_reminder_due
Sent when a configured appointment reminder becomes due. This event is delivered to organisation-level webhook subscriptions only.Reminders can also carry direct action links for the patient (join, reschedule, cancel) via RxScale’s own email/SMS content. The
rebook_allowed and cancel_allowed fields below tell you whether those actions are currently available — they are only ever true when recipient_role is patient.Payload Example
Field Reference
patient_doctor_meeting_updated
Sent when a patient-doctor meeting changes lifecycle state. This event is delivered to organisation-level webhook subscriptions only (registered via the Management API). Possiblechange values:
Use
change as the authoritative indicator of what happened. status reflects the meeting’s current database status and is null for on-demand meetings.Payload Example
Field Reference
Subscribing
Subscribe via the Management API to receive this event:Email notifications
Separately from webhooks, an organisation can have RxScale email the patient, the doctor, and/or its admins when a meeting is confirmed, cancelled, or rescheduled. Admins configure that from the Notifications tab in the admin portal, and it is off by default.confirmed is subscribable
independently of the other two changes — enabling it does not require also enabling cancellation
or rescheduling emails.
This does not change webhook behaviour. The event still fires on every transition listed
above, with the same payload, whether or not any email subscription exists. The webhook payload
itself is unchanged by this feature.
One difference is worth planning for: a reschedule publishes two events — cancelled for the
old meeting and rebooked for the new one — but sends at most one email, the rescheduling
one. If you mirror this stream into your own patient messaging, apply the same rule, or the
patient hears “cancelled” and then “moved”. confirmed is not part of a reschedule and has no
such pairing: it publishes once, for a fresh booking, and sends at most one confirmation email.
Delivery and Idempotency
Webhooks are delivered at least once. Your endpoint should treat deliveries as idempotent using the combination ofdata.meeting_uid and data.change as the unique key — retried deliveries will carry the same values.
review_request_updated
Sent when a review request you created changes. This event is delivered to organisation-level webhook subscriptions only (registered via the Management API). Possiblechange values:
No event is sent when the request is created (the create response answers that), or when a paid
order is linked to a request that is already cancelled or declined.
A booking through the link is announced twice: by
appointment_booked here, which ties the
appointment to the review request, and by
patient_doctor_meeting_updated with change: "confirmed", like
any other appointment. Later changes to the appointment, such as a cancellation or a no-show, are
reported only by patient_doctor_meeting_updated.
Use
change to see what happened. status is the request’s status after the change, and the two
can differ: assigned and appointment_booked come with the status the request already had, and a video_requested
after the draft order was created comes with status: "draft_created".Payload Example
appointment_booked event carries the booked appointment, and booking is null:
draft_created event carries the draft order instead, and booking is null:
Field Reference
The payload contains no patient name, contact details or clinical content: the patient is
identified only by
shop_identifier and shop_customer_id.
The booking link is pinned to the doctor: the patient can only book that doctor’s times. RxScale
takes no payment for it on your shops. Once the patient books, the appointment is reported by
patient_doctor_meeting_updated like any other appointment,
and for the review request by appointment_booked, which carries its meeting_uid.Subscribing
Subscribe via the Management API to receive this event:POST /v1/management/notification-subscriptions/test
and "event_type": "review_request_updated". No pharmacy order is needed.
Delivery and Idempotency
Each payload carries the state of the request at the moment of the change, not at delivery time. Webhooks are delivered at least once, and a retried delivery carries the same data with a newtimestamp. Build your processing around these rules:
assignedcan occur more than once for the same request, each time with a different doctor.video_requestedoccurs again only when the doctor replaced the link, which is possible only once the previous link expired unused or its appointment no longer stands.appointment_bookedoccurs once per booked appointment: after a replaced link, a second booking sends a second one, with a differentappointment.meeting_uid. Do not treatreview_request_uidandchangeas a unique key. Make processing a payload twice harmless instead, for example by sending the patient a booking link only if it differs from the one you already sent.- Deliveries can arrive out of order, for example when a delivery is retried. A final status
(
completed,declined,cancelled) never changes again, so ignore a payload with an open status once you have recorded a final one. - When in doubt, read the current state with
GET /v1/management/review-requests/{review_request_uid}.