This page is part of the FHIR Specification (v4.4.0: R5 Preview #2). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

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

2.47 Resource Subscription - Content

FHIR Infrastructure Work Group

Maturity Level: 0

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	The status of a subscription.	Required	SubscriptionState
Subscription.filterBy.searchModifier	Operator to apply to filter label.	Required	SubscriptionSearchModifier
Subscription.error	Codes to represent subscription error details.	Example	SubscriptionErrorCodes
Subscription.channelType	The type of method used to execute a subscription.	Extensible	SubscriptionChannelType
Subscription.contentType	The mime type of an attachment. Any valid mime type is allowed.	Required	Mime Types
Subscription.content	Codes to represent how much resource content to send in the notification payload.	Required	SubscriptionPayloadContent

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

Servers are responsible for following FHIR security guidance. 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 servers SHALL enforce authorization in accordance with their policy requirements. Servers 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, servers 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 channel type involves the server sending a communication that could reveal information about the client and server relationship, as well as sensitive administrative or clinical information. Servers are responsible for ensuring appropriate security is employed for each channel. The Subscription resource does not address these concerns directly; it is assumed that these are administered by other configuration processes. For instance, a server might maintain a whitelist of acceptable endpoints or trusted certificate authorities for rest-hook channels.

2.47.6 Subscription Notifications

This specification describes three distinct outbound notification types: Event, Handshake and Heartbeat. For each, the notification body is a subscription-notification Bundle with a SubscriptionStatus resource used to convey Subscription and notification details.

2.47.6.1 Event Notification

The primary notification is a notification about an event.

• Example event notification

The client expectations upon receipt of a Handshake notification are defined separately for each channel type (e.g., for the rest-hook channel type, a client endpoint responds to event notifications with standard HTTP response codes).

2.47.6.2 Handshake Notification

When a connection to an Endpoint is established, a server MAY send a Handshake notification to the endpoint. A Handshake notification is a subscription-notification Bundle sent without incrementing the subscription event count.

• Example handshake notification

The client is not expected to take any special action in receipt of a Handshake notification beyond the channel-specific requirement for receiving an event notification.

2.47.6.3 Heartbeat Notification

Servers MAY periodically send notifications across a channel to ensure that the connection is still alive and valid (e.g., in accordance with a client's requested heartbeat interval). The Heartbeat notification is an empty subscription-notification Bundle sent without incrementing the subscription event count.

• Example heartbeat notification

The client is not expected to take any special action in receipt of a Heartbeat notification beyond the channel-specific requirement for receiving an event notification.

2.47.6.4 Subscription Status

• The SubscriptionStatus.eventsSinceSubscriptionStart element indicates the number of unique events that have triggered notification attempts on this Subscription PRIOR to the current notification being sent.

  • In the case of a handshake, this count will always be zero (0).

  • In the case of a heartbeat notification, this count will be the same as the last notification and will not be incremented due to the heartbeat notification.

  • In the case of event notifications, the event count will be incremented by the number of notifications contained within this bundle (often a single notification, though servers may choose to batch notifications within a short time interval).

  • In the case of an event notification that cannot be delivered (e.g., because a client endpoint is offline), the server MAY retry delivery but does not increment the event count; the count represents unique events, not unique delivery attempts.

• The SubscriptionStatus.eventsInNotification element represents the number of event notifications conveyed by the Bundle. This helps clients:

  • Determine if a notification requires further processing (e.g., a client might discard handshake and heartbeat notifications)

  • Determine the number of events it should expeect to find in follow-on queries when the in empty payload type is used

  • Handle batched results (e.g., a server sending at max one notification per second)

  For handshake and heartbeat notifications, eventsInNotification will be zero if present.

• The SubscriptionStatus.status element represents the Subscription status values at the time the notification is sent. Note that the status might change between the time the notification is sent and the time it is received/processed, and therefore this status recorded in the extension is not guaranteed to represent status at the time of receipt. The field is useful as a hint to inform the client if the server has encountered errors in notifications immediately preceding this notification.

• The SubscriptionStatus.topic element references the SubscriptionTopic resource relevant to this notification, as an absolute URL for the SubscriptionTopic resource on the server that generated the notification (NOT a reference to a canonical SubscriptionTopic URL.)

• The SubscriptionStatus.subscription element references the Subscription resource that triggered this notification, as an absolute URL for the Subscription resource on the server that generated the notification.

2.47.6.5 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 entries.

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 for many real-world scenarios.

If a server will not honor a payload type (e.g., will not send full-resource over HTTP), the server should reject the Subscription request, but may accept it and report back to the subscriber that it was modified.

2.47.6.5.1 empty

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

With the content type of empty, the resources involved in triggering the notification are only available through the REST API, which helps 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 might query for the most recent Encounters for a patient or group of patients.

2.47.6.5.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 the REST API, which (as in the empty payload example) helps consolidate authorization and authentication logic. When the 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 might fetch the Encounter(s) for a patient or group of patients.

2.47.6.5.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 the subscriber receives a notification of this type, some resources are already present in the bundle, but it may need to fetch additional resources from the server. For example, the if the notification is for a topic about patient admission, the subscriber might fetch Observations related to the Encounters in the notification.

2.47.6.6 Payload Entries

In subscriptions with payloads of id-only or full-resource, the notification bundle will include data in the Bundle.entry appropriate to the requested type (e.g., fullURL or resource).

TODO: Each entry must be annotated to indicate whether it was gather before or after the event which caused the notification. For example, if the triggering event is a resource deletion, the before-object would be defined while the after-object would not. Conversely, during resource creation the before-object is not defined while the after-object is. Finally, during update operations, either the before or after object may meet the criteria, and this must be conveyed to the subscriber.

TODO: Issue: how do you handle security for these - e.g., a resource moves from permissable to not-permissable? You could trigger a notification with the before-object filled and the after-object not, but that indicates to the subscriber that a change has happened.

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.

2.47.7.1.1 Channel Security Notes

Note that HTTP is not a secure or encrypted channel. It is strongly recommended that implementations refuse requests to send notifications to URLs using the HTTP protocol (use HTTPS instead). Note that 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).

The subscriber then initiates a Web Socket connection to the server, at a URL advertised in the FHIR server's Capability statement (subscriptions/webSocketUrl (todo)). A simple protocol is used to listen for notifications:

• Client connects a secure Web Socket to the server's webSocketUrl (see websocket extension in the server's CapabilityStatement).
• Client authenticates to server using a server-specified Web socket protocol (e.g. OAuth bearer token presentation).
• Client sends a bind :id message over the socket (using the logical id of the subscription). For example, the client might issue: bind 123).
• Server responds with a "bound :id" message to acknowledge.
• Server sends a "ping :id" message to notify the client each time a new result is available

Trial-Use Note: Warning: The WebSocket channel type is being examined to provide functional parity with other channel types. In particular, the current system fails to address authentication and a desire for multiple subscriptions to be available to a single WebSocket connection. More work is required.

2.47.7.2.1 Channel Security Notes

WebSocket security for FHIR Subscriptions is not yet well understood. Implementers should be aware (at minimum) of the following areas:

• 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 for each matching resource. 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 MUST be human readable
• Message Attachments CAN 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 must 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.

Trial-Use Note: Warning: The Email channel type is still being actively tested and might not be consistently supported by servers. More work is required.

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 the message notification channel.

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

For each matching resource, a server will send a message to the nominated end-point. Most servers will require that the end-point is white-listed prior to allowing these kinds of subscriptions.

Trial-Use Note: Warning: The Messaging channel type is not yet defined in a highly standardized way, and might not be consistently supported by servers. More work is required.

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

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