• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles & Extensions
• Operations
• R3 Conversions

2.47 Resource Subscription - Content

FHIR Infrastructure Work Group

Maturity Level: 2

Trial Use

Security Category: Business

Compartments: Not linked to any defined compartments

The subscription resource describes a particular client's request to be notified about a SubscriptionTopic.

2.47.3 References

This resource is referenced by SubscriptionStatus.

This resource does not implement any patterns.

2.47.4 Resource Content

 

See the Profiles & Extensions and the alternate definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions, the spreadsheet version & the dependency analysis a

2.47.4.1 Terminology Bindings

Path	Definition	Type	Reference
Subscription.status		Required	SubscriptionState
Subscription.filterBy.resourceType		Extensible	FHIRDefinedType
Subscription.filterBy.searchModifier		Required	SubscriptionSearchModifier
Subscription.channelType		Extensible	SubscriptionChannelType
Subscription.contentType	The mime type of an attachment. Any valid mime type is allowed.	Required	Mime Types
Subscription.content		Required	SubscriptionPayloadContent
Subscription.notificationUrlLocation		Required	SubscriptionUrlLocation

Trial-Use Note:

TODO

1. Updates to "Managing Subscriptions and Errors"

   • Discuss error codes (Extensible Codeable Concept)
   • Define basic error codes here
   • Need to discuss eventCount and error detection (insert appropriate examples/workflows)

2. Updates to "Tracking Subscription Notifications" SHOULD define what the AuditEvent looks like

2.47.5 Safety and Security

Applications are responsible for following FHIR security guidance. Some recommendations specific to subscriptions are provided on the Subscriptions Framework page.

2.47.6 Payload Types

There are three options available when specifying the contents of a Notification: empty, id-only, and full-resource. These options change the level of detail conveyed in the notification Bundle.

When deciding which payload type to request, systems SHOULD consider both ease of processing and security of PHI. To mitigate the risk of information leakage, systems SHOULD use the minimum level of detail consistent with the use case. In practice, id-only provides a good balance between security and performance for many real-world scenarios.

If a server will not honor a payload type (e.g., will not send full-resource over HTTP), it SHOULD reject the Subscription request, but the server MAY accept the subscription with modificaitons.

2.47.6.1 empty

An example notification with an empty payload can be found here.

With the content type of empty, all information about the resources involved in triggering the notification is only available via channels other than the Subscription itself (e.g., the REST API). This mitigates many security concerns by both removing most PHI from the notification and allows servers to consolidate authorization and authentication logic. When the subscriber receives a notification of this type, it may query the server to fetch all the relevant resources based on the SubscriptionTopic and applicable filters. The client might include a _since= query parameter, supplying its last query timestamp to retrieve only the most recent resources. For example, if the notification is for a topic about patient admission, the subscriber will generally query for recent Encounters for a patient or group of patients, then fetch them as needed.

When the content type is empty, notification bundles SHALL not contain Bundle.entry elements other than the SubscriptionStatus for the notification.

2.47.6.2 id-only

An example notification with an id-only payload can be found here.

With the content type of id-only, the resources involved in triggering the notification are only available through other channels (e.g., REST API), but notifications include URLs which can be used to access those resources. This allows servers to consolidate authorization and authentication logic, while removing the need for expensive queries by subscribers. When a subscriber receives a notification of this type, it may directly fetch all the relevant resources using the supplied resource ids. For example, the if the notification is for a topic about patient admission, the subscriber may fetch the Encounter(s) for a patient or group of patients.

When the content type is id-only, notification bundles SHALL contain, in addition to the SubscriptionStatus, at least one Bundle.entry for each resource relevant to the notification. For example, a notification for a topic based on Encounter SHALL include a reference to the Encounter and MAY include additional resources deemed relevant (e.g., the linked Patient).

Each Bundle.entry for id-only notification SHALL contain a relevant resource URL in the fullUrl, request, and/or response elements. The Subscription's notificationUrlLocation element describes the behavior which should be used.

2.47.6.3 full-resource

An example notification with a full-resource payload can be found here.

With the content type of full-resource, the resources involved in triggering the notification are included in the notification bundle. When a subscriber receives a notification of this type, resources are already present in the bundle, though the subscriber may need to fetch additional resources from the server. For example, the if the notification is for a topic about patient admission, the subscriber may require related Observation resources.

When the content type is full-resource, notification bundles SHALL contain, in addition to the SubscriptionStatus, at least one Bundle.entry for each resource relevant to the notification. For example, a notification for a topic based on Encounter SHALL include an Encounter and MAY include additional resources deemed relevant (e.g., the relevant Patient).

In most scenarios, each Bundle.entry for a full-resource notification SHALL contain a relevant resource in the resource element. In some scenarios, it is not possible to include the resource, in which case entry.request and/or entry.response are required. For example, in the case of a notification about a deleted resource, the server may no longer have access to the resource. In this case, information in the entry.response is critical for a subscriber to process the notification (e.g., the etag).

2.47.7 Channels

2.47.7.1 REST Hook

When a Subscription is created for a REST Hook channel type, the server SHALL set initial status to requested, pending verification of the nominated endpoint URL. After a successful handshake notification has been sent and accepted, the server SHALL update the status to active. Any errors in the initial handshake SHALL result in the status being changed to error.

To receive notifications via HTTP/S POST, a client should request a subscription with the channel type (Subscription.channelType) of rest-hook (from the subscription-channel-type Code System) and set the endpoint (Subscription.endpoint) to the appropriate client URL. Note that this URL must be accessible by the hosting server.

To convey an event notification, the server POSTs a Bundle to the client's nominated endpoint URL per the format requests in the Subscription. The content-type of the POST SHALL match the contentType (channel.contentType) requested during creation of the Subscription. Each Subscription.header value SHALL be conveyed as an HTTP request header.

An example workflow for establishing a rest-hook subscription is included below.

1. Client creates a Subscription with the channelType set to rest-hook.
2. Server responds with a success code and creates the subscription with a state of requested.
3. Server performs an HTTP POST to the requested endpoint with a handshake notification.
4. Client Endpoint accepts the POST and returns a success HTTP code (e.g., 200).
5. Server may send a notification of type heartbeat at any time.
6. Server may send a notificaiton of type event-notificaiton at any time.

2.47.7.1.1 Channel Security Notes

HTTP is neither a secure nor an encrypted channel. It is strongly recommended that production implementations refuse requests to send notifications to URLs using the HTTP protocol (use HTTPS instead).

HTTP does not provide endpoint verification. It is strongly recommended that implementations refuse requests to send notifications to URLs using the HTTP protocol (use HTTPS instead).

2.47.7.2 WebSockets

While the primary interface for FHIR servers is the FHIR REST API, notifications need not occur via REST. Indeed, some subscribers may be unable to expose an outward-facing HTTP server to receive triggered notifications. For example, a pure client-side Web app or mobile app may want to subscribe to a data feed without polling using the /history operation. This can be accomplished using a websocket notification channel.

A client can declare its intention to receive notifications via Web Sockets by requesting a subscription with the channel type (Subscription.channelType) of websocket (from the subscription-channel-type Code System).

An example workflow for receiving notifications via websockets is shown below:

1. Client creates a Subscription with the channelType set to websocket.
2. Server responds with a success code and creates the subscription.
3. Client requests FHIR server's CapabilityStatement to find the server's websocket URL via the websocket extension.
4. Server returns its CapabilityStatement.
5. Client connects to the server via websockets (ws:// or wss://).
6. Client requests a websocket binding token, by invoking the $get-ws-binding-token operation via REST. Note: this call is intended to be repeated as necessary (e.g., prior to a token expiring, a client should request a new one).
7. Server returns Parameters with a token and an expiration.
8. Client sends a bind-with-token message via websockets, with the token provided by the server. Note: this operation can be repeated concurrently for multiple subscriptions, and serially for continued operation over a single websocket connection.
9. Server sends one or more handshake messages via websockets (one per Subscription included in the token). Note: some servers may additionally send one or more event-notification messages at this time (e.g., all messages since last connected, last 'n' messages, etc.). Clients are expected to handle either flow.
10. Server may send a heartbeat message via websockets at any time.
11. Server may send an event-notification message via websockets at any time.
12. Either the server or the client may close the websocket connection.

Note: all notifications sent from the server SHALL be in the format specified by the Subscription it is for (e.g., contentType and content fields).

Trial-Use Note: The Websocket channel type needs more testing and feedback to ensure all requirements are met before finalizing the specification.

2.47.7.2.1 Channel Security Notes

WebSocket security poses several challenges specific to the channel. When implementing websockets for notifications, please keep in mind the following list of some areas of concern:

• Authentication of WebSockets is not generically interoperable with JWT or other 'Authentication header' protocols - WS and WSS do NOT allow for the required headers.
• Given client limitations on concurrent WebSocket connections (commonly 6), it is recommended that a single connection be able to authenticate to multiple Subscription resources.
• Unlike HTTP/S requests, WebSockets can be long-lived. Because of this, the case of revoking access of an active connection must be considered.

2.47.7.3 Email

While the primary interface for FHIR servers is the FHIR REST API, notifications need not occur via REST. Indeed, some subscribers may be unable to maintain an outward-facing HTTP server to receive triggered notifications. For example, a public health organization may want to be notified of outbreaks of various illnesses. This can be accomplished using an email notification channel.

A client can declare its intention to receive notifications via Email by requesting a subscription with the channel type (Subscription.channelType) of email (from the subscription-channel-type Code System) and setting the endpoint (Subscription.endpoint) to the appropriate email URI (e.g., mailto:public_health_notifications@example.org).

The server will send a new message each time a notification should be sent (e.g., per event or per batch). The server will create a message based on the values present in the Subscription.contentType and Subscription.content fields. If a server cannot honor the requested combination, the server should reject the Subscription request rather than send unexpected email messages.

The email channel sets two guidelines about content:

• Message Body content SHALL be human readable
• Message Attachments SHOULD be machine readable

Due to these guidelines, the Subscription.contentType refers to the content of the body of the message. Attachment type information can be appended as a MIME parameter, for example:

• text/plain: a plain-text body with no attachment
• text/html: an HTML body with no attachment
• text/plain;attach=application/fhir+json: a plain-text body with a FHIR JSON bundle attached
• text/html;attach=application/fhir+xml: an HTML body with a FHIR XML bundle attached

The Subscription.content field SHALL be applied to any attachments, and MAY be applied to body contents (depending on server implementation). However, a server must not include a body which exceeds the specified content level. For example, a server may choose to always include a standard message in the body of the message containing no PHI and vary the attachment, but cannot include PHI in the body of an email when the content is set to empty.

An example workflow using the email channel type is included below.

1. Client creates a Subscription with the channelType set to email.
2. Server responds with a success code and creates the subscription with a state of either requested or active.
3. Optional: Server sends a email message to the requested endpoint with a handshake notification. If the subscription was set to requested, it should be updated to active after successfully sending the email (pending additional steps such as user confirmation, etc.).
4. Server may send an email for a notification of type heartbeat at any time.
5. Server may send an email for a notificaiton of type event-notificaiton at any time.

2.47.7.3.1 Channel Security Notes

Email (SMTP) is not a secure channel. Implementers must ensure that any messages containing PHI have been secured according to their policy requirements (e.g., use of a system such as Direct ).

2.47.7.4 Messaging

There are times when it is desireable to use Subscriptions as a communication channel between FHIR servers. This can be accomplished using a Subscription with the channel type of message.

To receive notifications via messaging, a client should request a subscription with the channel type (Subscription.channelType) of message and set the endpoint (Subscription.endpoint) to the destination FHIR server base URL. Note that this URL must be accessible by the hosting server.

The FHIR server hosting the subscription (server) will send FHIR messages to the destination FHIR server (endpoint) as needed. These messages will, as the contents of the message, have a fully-formed subscription-notification Bundle. An example message can be found here.

An example workflow using the message channel type is included below.

1. Client creates a Subscription with the channelType set to message.
2. Server responds with a success code and creates the subscription with a state of requested.
3. Server sends a FHIR Message to the requested endpoint with a handshake notification.
4. Client Endpoint accepts the Message and returns success.
5. Server may send a Message containing a notification of type heartbeat at any time.
6. Server may send a Message containing a notificaiton of type event-notificaiton at any time.

Trial-Use Note: The Messaging channel type needs more testing and feedback to ensure all requirements are met before finalizing the specification.

2.47.7.4.1 Channel Security Notes

Servers MAY require that the end-point is white-listed prior to allowing these kinds of subscriptions. Additionally, servers MAY impose authorization/authentication requirements for server to server communication (e.g., certificate pinning, etc.).

2.47.8 Defining Channel Types

Defining a new channel type requires clear communication to implementers of both clients and servers around requirements and expectations. Below are some areas which should be considered when creating a channel. Anyone defining a channel type is encouraged to publish their definition at registry.fhir.org .

Trial-Use Note: Warning: This section is still in early drafting.

2.47.8.1 Channel Basics

At a minimum, the following items should be defined:

• A generally useful name for Subscription.channelType (e.g., 'secure-mq' isntead of 'channel0012')
• The type of data required in Subscription.endpoint (e.g., URI, etc.)
• The meaning of the Subscription.header field values (e.g., REST-hook defines as Auth headers included in a POST)
• Any variations on MIME types for Subscription.contentType (e.g., email defines this as the email body, with allowable attachments.)
• Whether heartbeat notifications are used (and guidance on timings if they are)

2.47.8.2 Channel Security Considerations

• Defining a channel has security implications.
• If the channel CANNOT be secured, that should be stated with a warning not to transfer PHI.
• If the channel is/can be scured, guidance should be given on how configurations relate to PHI safety:
  • Does the channel determine the legitimacy of both endpoints?
  • Is the channel secure for third-party monitoring?
  • ...

2.47.9 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.

2.47.10 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Expression	In Common
contact	token	Contact details for the subscription	Subscription.contact
identifier	token	A subscription identifier	Subscription.identifier
payload	token	The mime-type of the notification payload
status N	token	The current state of the subscription	Subscription.status
type	token	The type of channel for the sent notifications
url	uri	The uri that will receive the notifications