Skip to main content

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.
New pharmacy orders start in the status 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.
Actual payment routing happens only when the pharmacy order is completed. projected payouts in webhook payloads are indicative, only shown for paid physical-prescription orders, and can change before completion. routed payout values are only populated after completion and routing exists.

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 .../status and complete_order calls), 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 sends pharmacy_order_updated with that shipment’s tracking number and URL, including when the order is already completed (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.
The payload structure is identical to 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_order with tracking_links creates a shipment and then sends pharmacy_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 already completed, you receive another pharmacy_order_updated with status: completed and the shipment on data.shipments, including tracking_number and tracking_url. The payload includes all current shipments, ordered by sequence_number.
  • pharmacy_order_created almost always has "shipments": []. Do not treat a missing tracking URL on create as an error.
How to consume it
  • Treat uid as the stable identity of a parcel. A later pharmacy_order_updated may add further entries; existing UIDs stay the same.
  • Prefer tracking_url for customer-facing tracking. tracking_number and carrier_name are present when the pharmacy or carrier supplied them; either can be null on a newly created placeholder shipment.
  • is_test is true only 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_number and tracking_url are null, because that parcel is no longer in transit.
  • return_tracking_number and return_label_expiry (YYYY-MM-DD) are set only after a return label is issued; otherwise they are null.
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 sku objects inside order_items and fulfillment.items are enriched with Shopify identifiers (shop_variation_id, shop_product_external_id).
  • A fulfillment object is added with fulfillment order details.
  • prescription_file is 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}/stock or 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 sku object is enriched with Shopify identifiers (shop_variation_id, shop_product_external_id).
  • A shop_identifier field is added at the data level.
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). Possible change 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 of data.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). Possible change 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".
You send the booking link to the patient. RxScale emails the link only to patients of an RxScale storefront. For your shops, the video_requested webhook is the only way the link reaches the patient. The link lets whoever opens it book an appointment for this patient, so send it to the patient only.

Payload Example

An appointment_booked event carries the booked appointment, and booking is null:
A 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:
To try your endpoint first, send a sample with 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 new timestamp. Build your processing around these rules:
  • assigned can occur more than once for the same request, each time with a different doctor. video_requested occurs 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_booked occurs once per booked appointment: after a replaced link, a second booking sends a second one, with a different appointment.meeting_uid. Do not treat review_request_uid and change as 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}.