> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rxscale.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks and Notifications
> How to set up webhook notifications for real-time order and prescription updates
# 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:
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.
Use the Management API to register your webhook endpoint URL. You will specify which event types you want to receive.
RxScale will send a test event to your endpoint. Make sure your server responds with a 200 status code to confirm it is working.
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:
| Event Type | When It Fires |
| --------------------------- | ----------------------------------------------------------------------------- |
| Order created | A new order has been placed. |
| Order updated | An order's status has changed (for example, moved to "waiting for pharmacy"). |
| Prescription approved | A doctor has approved a prescription. |
| Prescription signed | A prescription has been electronically signed. |
| Prescription declined | A doctor has declined a prescription. |
| Prescription doctor changed | The doctor assigned to a prescription has changed. |
| Pharmacy order updated | A pharmacy has updated an order's status (for example, shipped). |
For a complete list of event types and their payload formats, see the [Webhook Events](/webhooks/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 payload uses the prescription notification envelope with `category` set to `prescription` and `event` set to `doctor_changed`:
```json theme={null}
{
"category": "prescription",
"event": "doctor_changed",
"data": {
"shop_identifier": "telemedicine-shop",
"external_order_id": "order-100045",
"external_fulfillment_id": "fulfillment-100045-1",
"external_provider_identifier": "rxscale",
"doctor_assignment_reason": "ADMIN_ASSIGNED",
"old_doctor_uid": null,
"new_doctor_uid": "doctor_123",
"prescription": {
"uid": "prescription_123",
"created_at": "2026-05-21T14:30:00Z",
"status": "pending",
"doctor": {
"uid": "doctor_123",
"first_name": "Maria",
"last_name": "Schneider"
},
"patient_data": {
"first_name": "Alex",
"last_name": "Muster",
"date_of_birth": "1988-04-12"
},
"documents": [
{
"uid": "document_123",
"type": "prescription",
"status": "available"
}
],
"items": [
{
"uid": "prescription_item_123",
"shop_sku_uid": "shop_sku_123",
"fulfillment_line_item_external_id": "line-item-1"
}
]
}
}
}
```
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`.
## 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.
## 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](/webhooks/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.
## Related Topics
* [Webhooks Overview](/webhooks/overview) -- Technical details about how webhooks work.
* [Webhook Events](/webhooks/events) -- Complete list of event types and payload formats.
* [Webhook Security](/webhooks/security) -- How to verify webhook signatures.