> ## 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

> Register and manage organisation webhook subscriptions via the Management API

# Webhooks (Management API)

Register webhook subscriptions to receive real-time notifications for events across your organisation. For webhook payload formats and security, see the [Webhooks](/webhooks/overview) section.

<Note>
  These endpoints require the `notification_subscription` permissions: `notification_subscription:read` to list subscriptions, and `notification_subscription:write` to create, remove, or send a test webhook. A key without the required permission receives `403 Permission Denied`. See [Permissions](/permissions) for details.
</Note>

## List Webhook Subscriptions

Retrieve all active webhook subscriptions for your organisation.

```bash theme={null}
GET /v1/management/notification-subscriptions
```

### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/notification-subscriptions/" \
  -H "X-API-Key: your-api-key-here"
```

### Response

```json theme={null}
[
  {
    "uid": "ns-abc123",
    "notification_type": "pharmacy_order_created",
    "target": "https://your-system.com/webhooks/rxscale",
    "options": "WEBHOOK",
    "payload_version": "1"
  }
]
```

## Register Webhook Subscription

Create a new webhook subscription for your organisation.

```bash theme={null}
POST /v1/management/notification-subscriptions
```

### Request Body

```json theme={null}
{
  "notification_type": "pharmacy_order_created",
  "target": "https://your-system.com/webhooks/rxscale",
  "payload_version": "1"
}
```

| Field               | Type   | Required | Description                                          |
| ------------------- | ------ | -------- | ---------------------------------------------------- |
| `notification_type` | string | Yes      | Event type to subscribe to                           |
| `target`            | string | Yes      | Webhook URL to receive notifications (must be HTTPS) |
| `meta_data`         | object | No       | Optional metadata for the subscription               |
| `payload_version`   | string | No       | Payload schema version (default: `"1"`)              |

### Available Event Types

| Event Type                       | Description                                      |
| -------------------------------- | ------------------------------------------------ |
| `pharmacy_order_created`         | A new pharmacy order has been created            |
| `pharmacy_order_updated`         | An existing order's status has changed           |
| `pharmacy_sku_stock_updated`     | Stock level changed for a pharmacy SKU           |
| `patient_doctor_meeting_updated` | A patient-doctor meeting changed lifecycle state |

### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/notification-subscriptions/" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_type": "pharmacy_order_created",
    "target": "https://your-system.com/webhooks/rxscale"
  }'
```

### Response (201 Created)

```json theme={null}
{
  "uid": "ns-abc123",
  "notification_type": "pharmacy_order_created",
  "target": "https://your-system.com/webhooks/rxscale",
  "options": "WEBHOOK",
  "payload_version": "1"
}
```

## Remove Webhook Subscription

Delete (deactivate) a webhook subscription by specifying the target URL and notification type.

```bash theme={null}
DELETE /v1/management/notification-subscriptions
```

<ParamField query="target" type="string" required>
  The webhook target URL
</ParamField>

<ParamField query="notification_type" type="string" required>
  The notification type to unsubscribe from
</ParamField>

### Example Request

```bash theme={null}
curl -X DELETE "https://api.rxscale.com/v1/management/notification-subscriptions/?target=https://your-system.com/webhooks/rxscale&notification_type=pharmacy_order_created" \
  -H "X-API-Key: your-api-key-here"
```

Returns `204 No Content` on success.

## Test Webhook Delivery

Send a sample webhook payload to a target URL to verify your endpoint is configured correctly. This is useful for verifying your webhook endpoint is working before creating a subscription.

```bash theme={null}
POST /v1/management/notification-subscriptions/test
```

### Request Body

```json theme={null}
{
  "target_url": "https://your-system.com/webhooks/rxscale",
  "event_type": "pharmacy_order_created",
  "header_key": "X-Custom-Auth",
  "header_value": "my-secret-token"
}
```

| Field          | Type   | Required | Description                                                   |
| -------------- | ------ | -------- | ------------------------------------------------------------- |
| `target_url`   | string | Yes      | URL to send the test webhook to (must be HTTPS)               |
| `event_type`   | string | No       | Type of event to simulate (default: `pharmacy_order_created`) |
| `header_key`   | string | No       | Custom header name to include in the test request             |
| `header_value` | string | No       | Custom header value to include in the test request            |

### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/notification-subscriptions/test" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-system.com/webhooks/rxscale",
    "event_type": "pharmacy_order_created",
    "header_key": "X-Custom-Auth",
    "header_value": "my-secret-token"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "status_code": 200,
  "payload_sent": {
    "event_type": "pharmacy_order_created",
    "timestamp": 1711700000,
    "payload_version": "1",
    "data": { ... }
  }
}
```

<Note>
  Test webhook payloads include the header `X-Webhook-Test: true` so your endpoint can distinguish test deliveries from real ones.
</Note>