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:
Event TypeWhen It Fires
Order createdA new order has been placed.
Order updatedAn order’s status has changed (for example, moved to “waiting for pharmacy”).
Prescription approvedA doctor has approved a prescription.
Prescription signedA prescription has been electronically signed.
Prescription declinedA doctor has declined a prescription.
Prescription doctor changedThe doctor assigned to a prescription has changed.
Pharmacy order updatedA 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 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: 
{
  "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 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.