This page is part of the FHIR Specification (v4.5.0: R5 Preview #3). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions

3.8 Subscriptions Framework

FHIR Infrastructure Work Group

Maturity Level: 0

Standards Status: Draft

Subscriptions are used to establish proactive event notifications from a FHIR application to another system. Applications which have implemented support for Subscriptions will advertise their use via the resources Subscription and SubscriptionTopic. Operations allowed on these resources may be discovered via the FHIR Application's CapabilityStatement.

This document contains general information about the Subscriptions framework in FHIR. Documentation about specific values (e.g., the rest-hook channel type) can be found in the appropriate resource documentation. For convenience, below is a list of common topics and links to their documentation.

Resource	Topic
SubscriptionTopic	Resource
	Defining Topics
	Deriving from existing Topics
Subscription	Resource
	Payload Options
	Standard Channels
	Creating Channels
	$status Operation
SubscriptionStatus	Resource
	Notification Types

3.8.1 Actors and Roles

Any FHIR application may support the use of Subscriptions. In this documentation:

• Server refers to the FHIR application or applications acting as the subscription provider. This includes the responsibilities of implmenting one or more SubscriptionTopics, managing Subscriptions, and sending notifications.
• Client refers to the application or applications acting as subscriber. This includes the responsibilites of acting as a FHIR client (to request a Subscription) and receiving notifications on a supported channel.

Note: either role may be implemented by one or more applications across one or more systems.

3.8.2 General Overview

The Subscriptions Framework in FHIR is a mechanism used to send notifications from a server to a client based on activity occuring in the server.

The Subscription mechanism is composed of three parts:

• SubscriptionTopic resources
  • Define the data and change used to trigger notifications
  • Define the filters allowed to clients
• Subscription resources
  • Describe a client's request to be notified about events defined in a SubscriptionTopic
  • Set filters on events (as defined in the referenced SubscriptionTopic)
  • Describe the channel and endpoint used to send notifications
  • Describe the payload included in notifications (MIME type, content level, etc.)
• subscription-notification Bundles
  • Describe a notification (using a SubscriptionStatus)
  • Contain zero or more notification payloads

3.8.2.1 Subscription Topics

3.8.2.2 Subscriptions

3.8.2.3 Subscription Notifications

3.8.3 Safety and Security

Applications are responsible for following FHIR security guidance. Some recommendations specific to subscriptions are provided below.

A subscription is a request for future event notifications. As with any client-initiated interaction, Subscriptions could request information that a client is not allowed to see, and applications SHALL enforce authorization in accordance with their policy requirements. Applications SHOULD take a subscription's SubscriptionTopic and filters into account when authorizing the creation of a Subscription, and SHOULD ensure that authorization is (still) in place at the time of each event notification.

When sending an event notification, applications can adopt various strategies to ensure that authorization is still in place. Some strategies may provide imperfect assurance (e.g., a server might rely on signed tokens with some pre-specified lifetime as evidence of authorization). In addition to these strategies, servers can mitigate the risk of disclosing sensitive information by limiting the payload types it supports (e.g., by prohibiting certain clients from requesting full-resource notification payloads and relying instead on id-only payloads).

Subscription resources are not intended to be secure storage for secrets (e.g., OAuth Client ID or Tokens, etc.). Implementers MAY use their judgement on including limited-use secrets (e.g., a token supplied in Subscription.header to verify that a message is from the desired source).

Each notification sent by the application could reveal information about the application and subscriber relationship, as well as sensitive administrative or clinical information. Applications are responsible for ensuring appropriate security is employed for each channel they support. The Subscription resource does not address these concerns directly; it is assumed that these are administered by other configuration processes. For instance, an application might maintain a whitelist of acceptable endpoints or trusted certificate authorities for rest-hook channels.

3.8.4 Managing Subscriptions and Errors

The subscription resource is authored by the client with an initial status of requested. A new subscription is created on the server using the RESTful create or update interaction. After a successful transaction, the client parses the Location header and saves the new Subscription's logical id for use in subsequent operations.

When the server receives a subscription, it SHOULD check that it is prepared to accept/process the subscription. If it is, it sets the subscription to requested and process it like a normal create. If it isn't, it SHOULD return an error with an OperationOutcome instead of processing the create.

The criteria are subject to the same limitations as the client that created it, such as access to patient compartments etc. Note that the subscription MAY remain active after the client access tokens expire.

Once the server has activated the subscription, it sets the status to active (note: the server may do this as it accepts the resource if it wants).

An appropriately authorized client can use search and/or history operations to see what subscriptions are currently active on the server. Once the subscription is no longer desired, the client deletes the subscription from the server.

The server may retry the notification a fixed number of times and/or refer errors to its own alert logs. If the notification fails, the server SHOULD set the status to error and mark the error in the resource. If the notification succeeds, the server SHOULD update the status to active and may remove any error codes. If a subscription fails consistently a server may choose set the subscription status to off and stop trying to send notifications.

Errors a server wishes to make accessible to clients are stored in Subscription.error. Servers should provide a mechanism for clearing errors (e.g., when resetting a Subscription.status back to requested after an error). Since Subscription.error represents server errors, a server SHOULD NOT allow clients to add errors.

3.8.5 Tracking Subscription Notifications

Servers implementing Subscriptions are responsible for complying with their policies on information logging. Servers are encouraged to track all sent notifications, for example with the use of AuditEvent or Communication resources.