Webhooks (External Pharmacy API)

Register webhooks to receive real-time notifications when pharmacy orders are created, updated, or when stock levels change.

Listing webhooks requires the webhooks_read permission; registering and removing them requires webhooks_write. A key without the required permission receives 403.

List Webhooks

GET /v1/external_pharmacy_api/webhooks/

Returns the webhook subscriptions of your pharmacy group. With a single-pharmacy API key, the list contains only subscriptions scoped to that pharmacy — group-wide subscriptions, such as those registered in the Pharmacy Portal, are not listed.

curl -X GET "https://api.rxscale.com/v1/external_pharmacy_api/webhooks/" \
  -H "X-API-Key: your-api-key-here"

Response

[
  {
    "uid": "sub-abc123",
    "target": "https://your-system.com/webhooks/rxscale",
    "notification_type": "pharmacy_order_created",
    "pharmacy_uid": null,
    "header_key": "X-Custom-Auth"
  }
]

The webhook_secret and the value of the custom header are never returned. The response can contain additional fields; ignore fields you do not use.

Register Webhook

POST /v1/external_pharmacy_api/webhooks/

Request Body

string

required

The URL that receives the webhook requests. It must be an https:// URL whose host resolves to a public IP address. localhost, *.local hosts, private or internal IP addresses, and hosts that cannot be resolved are rejected with 400.

string

required

The event to subscribe to: pharmacy_order_created, pharmacy_order_updated, or pharmacy_sku_stock_updated. Each subscription covers exactly one event type, so register one subscription per event you want to receive.

string

Scopes the subscription to one pharmacy.

With a single-pharmacy API key, the subscription is always scoped to that key’s pharmacy, and this field is ignored.
With a group-wide API key, the pharmacy must belong to your pharmacy group; otherwise the request fails with 400. Omit the field to create a group-wide subscription that receives the events of every pharmacy in the group.

string

Name of a custom HTTP header that RxScale sends with every delivery — for example to authenticate against your endpoint. 1–255 characters. Send it together with header_value. Must be a valid HTTP header name: letters, digits, hyphens and underscores (for example X-Api-Key), with no spaces or colons. The reserved names Content-Type, X-Webhook-Event, X-Webhook-Signature, X-Webhook-Test and connection-level headers such as Host, Content-Length, Transfer-Encoding, Connection and Proxy-Authorization are rejected (case-insensitive).

string

Value of the custom header. 1–4096 characters. Required when header_key is set, and must be omitted otherwise. It is stored encrypted and never returned.

curl -X POST "https://api.rxscale.com/v1/external_pharmacy_api/webhooks/" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://your-system.com/webhooks/rxscale",
    "notification_type": "pharmacy_order_created",
    "header_key": "X-Custom-Auth",
    "header_value": "my-secret-token"
  }'

Response (201 Created)

{
  "uid": "sub-abc123",
  "target": "https://your-system.com/webhooks/rxscale",
  "notification_type": "pharmacy_order_created",
  "pharmacy_uid": null,
  "header_key": "X-Custom-Auth",
  "webhook_secret": "EXAMPLE_webhook_secret_returned_only_once"
}

The webhook_secret is only returned in this response and cannot be retrieved later. Store it securely — you’ll need it to verify webhook signatures. See Webhook Security for details.

Registering the Same Subscription Again

A subscription is identified by its notification_type, target, and pharmacy_uid. If you register the same combination again — even after deleting it — RxScale keeps the existing uid, issues a new webhook_secret (the old one stops working immediately), and replaces the custom header. If you omit header_key and header_value, the custom header is removed. You can use this to rotate the secret — see Rotating the Secret.

Errors

Status	Cause
`400`	Invalid request body — for example a `target` that is not a public HTTPS URL, an unknown `notification_type`, `header_key` without `header_value`, a reserved header name, or a `pharmacy_uid` outside your pharmacy group
`403`	The API key lacks the `webhooks_write` permission

Remove Webhook

DELETE /v1/external_pharmacy_api/webhooks/{subscription_uid}

curl -X DELETE "https://api.rxscale.com/v1/external_pharmacy_api/webhooks/sub-abc123" \
  -H "X-API-Key: your-api-key-here"

Returns 204 No Content on success. No further deliveries are sent for the subscription, including retries of earlier events. Returns 404 if the subscription does not exist or is not visible to your API key. A single-pharmacy API key can only remove subscriptions scoped to its pharmacy.

How Events Reach Your Subscriptions

An event for a pharmacy is delivered to every subscription of that pharmacy’s group that is either group-wide (pharmacy_uid is null) or scoped to that pharmacy.

If you have both a group-wide and a pharmacy-scoped subscription for the same event, you receive each event for that pharmacy twice — once per subscription.
Subscriptions registered in the Pharmacy Portal are always group-wide.
Each subscription has its own webhook_secret, and deliveries do not identify the subscription they belong to. Use a separate target URL for each subscription (for example a different path) so you always know which secret to verify with.

Available Event Types

Event Type	Description
`pharmacy_order_created`	A new pharmacy order has been created
`pharmacy_order_updated`	An existing order changed, including status updates and shipments added by the pharmacy
`pharmacy_sku_stock_updated`	Stock level changed for one of your SKUs

See Webhook Events for full payload details.

Getting Started

External Pharmacy API

Management API

Scheduling API

Public API

Patient API

Anamnesis API

Webhooks

Guides

Webhooks

Webhooks (External Pharmacy API)

List Webhooks

Response

Register Webhook

Request Body

Response (201 Created)

Registering the Same Subscription Again

Errors

Remove Webhook

How Events Reach Your Subscriptions

Available Event Types

​Webhooks (External Pharmacy API)

​List Webhooks

​Response

​Register Webhook

​Request Body

​Response (201 Created)

​Registering the Same Subscription Again

​Errors

​Remove Webhook

​How Events Reach Your Subscriptions

​Available Event Types

Webhooks (External Pharmacy API)

List Webhooks

Response

Register Webhook

Request Body

Response (201 Created)

Registering the Same Subscription Again

Errors

Remove Webhook

How Events Reach Your Subscriptions

Available Event Types