Subscriptions

Fire Arrow Server supports FHIR Subscriptions for real-time notifications when resources change. Define criteria-based subscriptions to receive webhooks, emails, websocket messages, or Azure Storage Queue messages whenever matching resources are created or updated.

Supported Channels

Channel Type	Description	Use Case
rest-hook	HTTP POST to a URL	Backend integrations, webhooks
email	Send email notification	Alerts to practitioners, administrators
websocket	Push via WebSocket connection	Real-time UI updates in web apps
message	Azure Storage Queue message	Async processing, decoupled architectures

Creating a Subscription

Create a FHIR Subscription resource with your desired criteria and channel:

REST Hook

curl -X POST http://localhost:8080/fhir/Subscription \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceType": "Subscription",
    "status": "requested",
    "criteria": "Observation?patient=Patient/123",
    "channel": {
      "type": "rest-hook",
      "endpoint": "https://your-app.example.com/webhooks/observations",
      "payload": "application/fhir+json",
      "header": ["Authorization: Bearer webhook-secret-123"]
    },
    "end": "2026-06-28T00:00:00Z"
  }'

The criteria field uses the same search syntax as FHIR REST search. When a resource matching the criteria is created or updated, Fire Arrow Server sends an HTTP POST to the specified endpoint.

Email

curl -X POST http://localhost:8080/fhir/Subscription \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceType": "Subscription",
    "status": "requested",
    "criteria": "Task?status=failed",
    "channel": {
      "type": "email",
      "endpoint": "mailto:[email protected]",
      "payload": "application/fhir+json"
    },
    "end": "2026-06-28T00:00:00Z"
  }'

WebSocket

curl -X POST http://localhost:8080/fhir/Subscription \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceType": "Subscription",
    "status": "requested",
    "criteria": "Encounter?patient=Patient/123&status=in-progress",
    "channel": {
      "type": "websocket"
    },
    "end": "2026-06-28T00:00:00Z"
  }'

Connect to the WebSocket endpoint at ws://localhost:8080/websocket to receive notifications for this subscription.

Azure Storage Queue

For decoupled, asynchronous processing, Fire Arrow Server can deliver subscription notifications to an Azure Storage Queue:

curl -X POST http://localhost:8080/fhir/Subscription \
  -H "Content-Type: application/fhir+json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "resourceType": "Subscription",
    "status": "requested",
    "criteria": "DiagnosticReport?status=final",
    "channel": {
      "type": "message"
    },
    "end": "2026-06-28T00:00:00Z"
  }'

Messages are delivered to the Azure Storage Queue configured in fire-arrow.subscription.azure-queue. Each message contains the resource reference and subscription ID, allowing your queue consumer to fetch the full resource.

Subscription Lifecycle

Subscriptions go through the following statuses:

1. requested -- you create the Subscription with this status
2. active -- the server validates and activates the Subscription
3. off -- the Subscription's end date has passed
4. error -- too many consecutive delivery failures (configurable threshold)

Required End Date

The end field is required on all Subscriptions. The server enforces a maximum TTL -- if your end date exceeds the allowed maximum, the server will reject the Subscription. Use a reasonable end date and renew subscriptions as needed.

Authorization

Subscription creation requires a subscribe authorization rule:

fire-arrow:
  authorization:
    validation-rules:
      - client-role: "Practitioner"
        resource: "Subscription"
        operation: "subscribe"
        validator: "LegitimateInterest"
      - client-role: "Patient"
        resource: "Subscription"
        operation: "subscribe"
        validator: "PatientCompartment"

Configuration

Enabling Subscriptions

Enable subscription support in your application.yaml:

hapi:
  fhir:
    subscription:
      resthook_enabled: true
      email:
        enabled: true
        from: "[email protected]"
      websocket_enabled: true

Azure Storage Queue

To use the Azure Storage Queue channel, configure the queue connection:

fire-arrow:
  subscription:
    azure-queue:
      enabled: true
      connection-string: "${AZURE_STORAGE_CONNECTION_STRING}"
      queue-name: "fhir-subscription-events"

Property	Description
enabled	Enable the Azure Storage Queue channel
connection-string	Azure Storage account connection string
queue-name	Name of the queue to deliver messages to

Full Subscription Configuration

hapi:
  fhir:
    subscription:
      resthook_enabled: true
      websocket_enabled: true
      email:
        enabled: true
        from: "[email protected]"

fire-arrow:
  subscription:
    azure-queue:
      enabled: true
      connection-string: "${AZURE_STORAGE_CONNECTION_STRING}"
      queue-name: "fhir-subscription-events"

Environment Variable Overrides

YAML Path	Environment Variable
hapi.fhir.subscription.resthook_enabled	HAPI_FHIR_SUBSCRIPTION_RESTHOOK_ENABLED
hapi.fhir.subscription.websocket_enabled	HAPI_FHIR_SUBSCRIPTION_WEBSOCKET_ENABLED
hapi.fhir.subscription.email.enabled	HAPI_FHIR_SUBSCRIPTION_EMAIL_ENABLED
fire-arrow.subscription.azure-queue.connection-string	FIRE_ARROW_SUBSCRIPTION_AZURE_QUEUE_CONNECTION_STRING
fire-arrow.subscription.azure-queue.queue-name	FIRE_ARROW_SUBSCRIPTION_AZURE_QUEUE_QUEUE_NAME