Skip to main content

Webhooks and Notifications

Webhooks let RxScale notify your system in real time when something happens — such as an order status change, a prescription being signed, or a pharmacy shipping an order. This page explains how to set up and use webhooks effectively.

Setting Up Webhooks

To start receiving webhook notifications:
1

Prepare your endpoint

Create an HTTP endpoint on your server that can receive POST requests. This endpoint should be publicly accessible and able to handle incoming webhook payloads.
2

Register your webhook

Use the Management API to register your webhook endpoint URL. You will specify which event types you want to receive.
3

Verify your setup

RxScale will send a test event to your endpoint. Make sure your server responds with a 200 status code to confirm it is working.
4

Start receiving events

Once registered, your endpoint will receive webhook notifications for the event types you subscribed to.

Available Event Types

RxScale sends webhook notifications for a variety of events. Here are the most common ones: For a complete list of event types and their payload formats, see the Webhook Events documentation.

Prescription doctor assignment changes

If you subscribe to Pub/Sub notifications, RxScale can publish a dedicated event whenever the doctor assigned to a prescription changes. Subscribe to the notification type PRESCRIPTION_DOCTOR_CHANGED to receive these updates. The topic must be in your own Google Cloud project; RxScale does not publish this event to a topic in RxScale’s project. The payload uses the prescription notification envelope with category set to prescription and event set to doctor_changed:
The data object contains the public prescription payload plus the fields external_provider_identifier, doctor_assignment_reason, old_doctor_uid, and new_doctor_uid. old_doctor_uid is null when a prescription was not assigned to a doctor before the change. new_doctor_uid is null when the assignment was removed. doctor_assignment_reason describes why RxScale changed the assignment. Stable reason examples include ADMIN_ASSIGNED, ORDER_ATTRIBUTE_ASSIGNED, QUEUE_ASSIGNED, PRESCRIPTION_REQUEUED, DOCTOR_REQUEUED_PRESCRIPTIONS, STALE_ASSIGNMENT_CLEARED, and ON_HOLD_DOCTOR_REMOVED. Archiving a doctor puts that doctor’s pending prescriptions (waiting for a doctor, or approved and not yet signed) back on the queue. Each of those releases sends doctor_changed with doctor_assignment_reason DOCTOR_REQUEUED_PRESCRIPTIONS and new_doctor_uid null. An internal hold (ON_HOLD still assigned to that doctor) is released to the organisation: the status stays ON_HOLD, and doctor_changed is sent with doctor_assignment_reason ON_HOLD_DOCTOR_REMOVED and new_doctor_uid null. Signed prescriptions stay with the doctor and do not send this event. Archive does not cancel the doctor’s appointments and does not send patient_doctor_meeting_updated for them. Queue sharing sends no events of its own. Reserving a new prescription for the share holder does not assign it, and a reservation that times out does not unassign anything, so neither produces a doctor_changed event. You receive a single QUEUE_ASSIGNED event when a doctor takes the prescription.
Treat doctor_assignment_reason as an open set. RxScale adds new reasons as review workflows evolve, so handle unrecognised values gracefully rather than rejecting the message.

Monitoring Order Status Changes

Webhooks are the best way to stay informed about what is happening with your orders. Instead of polling the API repeatedly, you receive a notification the moment something changes. A typical monitoring workflow:
  1. A patient places an order on your shop.
  2. You receive a webhook when the order is created.
  3. You receive a webhook when the doctor approves the prescription.
  4. You receive a webhook when the prescription is signed.
  5. You receive a webhook when the order is sent to a pharmacy.
  6. You receive a webhook when the pharmacy ships the order.
  7. You receive a webhook when the order is completed.
Each notification includes the relevant order or prescription data, so you can update your systems and inform your patients at every step.

Email When a Pharmacy Cancels an Order

If your support team should hear about it when a pharmacy cancels one of your orders, RxScale can email your shop’s support address. The email is off unless you turn it on, per shop:
  1. In the admin app, open Settings → Shops.
  2. Make sure the shop has a support email. Edit the shop to set one.
  3. Open Configure Shop for the shop and turn on Email shop support when a pharmacy cancels an order.
The email is sent each time the pharmacy cancels one of the shop’s pharmacy orders, in the Pharmacy Portal or through the Pharmacy API. It is not sent when RxScale cancels the order, for example when an admin cancels it or the order moves to another pharmacy. The subject names the pharmacy, for example Apotheke am Markt hat die Pharmacy Order storniert / Apotheke am Markt cancelled the pharmacy order. The body is in German and English and contains:
  • the UID of the pharmacy order
  • the UID of the order
  • a link to the order in the admin app
The pharmacy order’s activity log records that your support was notified and the address the email went to. A shop with the setting on but no support email gets no email. The pharmacy_order_updated webhook still arrives as before, so an integration that already listens for cancellations needs no change.

Email When a Prescription Is Signed

RxScale can also email your shop’s support address each time a doctor signs the prescription for one of the shop’s orders. This email is also off unless you turn it on, per shop:
  1. In the admin app, open Settings → Shops.
  2. Make sure the shop has a support email. Edit the shop to set one.
  3. Open Configure Shop for the shop and turn on Email shop support when a prescription is signed.
The subject names the order by its shop order number, for example Rezept zur Bestellung #1001 signiert / Prescription for order #1001 signed. When the order has no shop order number, its RxScale order UID is used instead. The body is in German and English and contains:
  • the UID of the prescription
  • the UID of the order
  • a link to the order in the admin app
The email names neither the patient nor the medicine. A shop with the setting on but no support email gets no email.

Best Practices for Webhook Handling

Your endpoint should respond with a 200 status code as quickly as possible. Process the webhook payload asynchronously if needed — do not block the response while performing lengthy operations.
In rare cases, you may receive the same webhook event more than once. Design your handler to be idempotent, meaning processing the same event twice should not cause issues.
RxScale signs webhook payloads so you can verify they are authentic. Always verify the signature before processing the payload. See Webhook Security for details.
If your endpoint is down or returning errors, webhook deliveries will be retried. Set up monitoring to detect when your endpoint is failing so you can fix issues quickly.
Keep a log of all received webhook events. This is invaluable for debugging and understanding the sequence of events for any given order.