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 typePRESCRIPTION_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:
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:- A patient places an order on your shop.
- You receive a webhook when the order is created.
- You receive a webhook when the doctor approves the prescription.
- You receive a webhook when the prescription is signed.
- You receive a webhook when the order is sent to a pharmacy.
- You receive a webhook when the pharmacy ships the order.
- You receive a webhook when the order is completed.
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:- In the admin app, open Settings → Shops.
- Make sure the shop has a support email. Edit the shop to set one.
- Open Configure Shop for the shop and turn on Email shop support when a pharmacy cancels an order.
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
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:- In the admin app, open Settings → Shops.
- Make sure the shop has a support email. Edit the shop to set one.
- Open Configure Shop for the shop and turn on Email shop support when a prescription is signed.
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
Best Practices for Webhook Handling
Respond quickly
Respond quickly
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.
Handle duplicates
Handle duplicates
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.
Verify the payload
Verify the payload
RxScale signs webhook payloads so you can verify they are authentic. Always verify the signature before processing the payload. See Webhook Security for details.
Monitor for failures
Monitor for failures
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.
Log webhook events
Log webhook events
Keep a log of all received webhook events. This is invaluable for debugging and understanding the sequence of events for any given order.
Related Topics
- Webhooks Overview — Technical details about how webhooks work.
- Webhook Events — Complete list of event types and payload formats.
- Webhook Security — How to verify webhook signatures.