FHIR Subscription

Clients register interest in specific FHIR resources by creating a Subscription resource that defines a topic (the event type) and criteria (a FHIRPath or query expression). The server evaluates incoming changes against active subscriptions and sends notifications when criteria are met. Supported topics include create, update, and delete operations on any resource type.

• Criteria string: Defines the filter, e.g., Observation?code=http://loinc.org|8867-4 for heart rate observations
• Channel type: Specifies the delivery mechanism (REST hook, websocket, email, or message queue)
• Payload: Can be id-only, full-resource, or a custom subset defined by an _include parameter

The most common delivery mechanism where the FHIR server sends an HTTP POST to a pre-registered endpoint when a matching event occurs. The notification payload contains either the full resource or a reference, allowing the receiving system to act immediately.

• Endpoint registration: The client provides a callback URL in the channel.endpoint field
• Payload MIME type: Typically application/fhir+json
• Security headers: Custom headers can be included for bearer token authentication or API key validation
• Retry logic: Servers implement exponential backoff on delivery failure, with configurable timeout and retry counts

For low-latency use cases like patient monitoring dashboards, the websocket channel type maintains a persistent, bidirectional connection. The client establishes a WebSocket handshake, and the server pushes notifications as they occur without the overhead of repeated HTTP connections.

• Connection lifecycle: Client initiates via ws:// or wss:// protocol
• Heartbeat mechanism: Ping/pong frames maintain connection health
• Use case: Real-time vital sign streaming for ICU dashboards
• Advantage: Eliminates polling latency and reduces server load compared to frequent REST queries

When a resource change matches a subscription's criteria, the server executes a defined workflow: evaluate the criteria against the change, construct the notification bundle, and deliver via the specified channel. The server records the delivery status in a SubscriptionStatus resource for auditability.

• Evaluation: Server checks if the changed resource satisfies the criteria FHIRPath expression
• Bundle construction: Notification is wrapped in a history or searchset Bundle
• Delivery tracking: Each notification attempt is logged with timestamp and HTTP status
• Error handling: Failed deliveries trigger retry with exponential backoff (e.g., 1s, 2s, 4s, 8s)

Subscriptions use FHIRPath to define precise matching conditions beyond simple resource type filters. This path-based language allows complex boolean logic, enabling subscriptions like 'notify me only for critical lab results from oncology patients.'

• Example: %resource.code.coding.where(system='http://loinc.org' and code='718-7').exists() matches hemoglobin results
• Context variables: %resource refers to the changed resource, %previous to the prior version
• Operators: Supports =, !=, >, <, contains, exists, all, where, and logical and/or
• Limitation: FHIRPath evaluation is limited to the resource content; cross-resource joins require server-side extensions

Every subscription has an associated SubscriptionStatus resource that tracks the operational state, including the last event processed, notification delivery history, and any errors encountered. This provides the observability required for production-grade federated learning pipelines.

• Status values: active, error, off, requested
• Event count: Tracks total notifications sent and failed deliveries
• Last event timestamp: Records when the most recent matching event was processed
• Error details: Includes HTTP status codes and error messages for debugging delivery failures