Short Description

Topic-based subscriptions are now available in FHIR R4B.  This track will focus on the implementation of topic-based subscriptions, as well as discussions about subscription topics and channel types. 

Long Description

Topic-based subscriptions enable subscribers to receive notifications when events occur.  This enables server-driven workflows and allows clients to avoid polling for data changes.  In addition to testing implementations of R4B, this Connectathon will likely be the last opportunity to test and provide feedback for R5.


Implementation Development, Specification Testing, IG Development (IGs with a dependency on subscriptions)

Track Prerequisites

  • Basic understanding of Topic-Based Subscriptions (video from C29, will update Soon(tm))
  • Basic understanding of the components of Topic-Based Subscriptions

Track Lead(s)

Track Lead Email(s)

Specification Information

R4B: Subscriptions Backport IG, R4B Resources: SubscriptionTopic, SubscriptionStatus

R5: Subscriptions Overview, Subscription, SubscriptionTopic, SubscriptionStatus

Call for participants

Developers working on the implementation of Subscriptions.

Implementors wanting to test and provide feedback for FHIR R5.

Authors working on IGs built on top of subscriptions.

Zulip stream


Track Kick off Call

Tuesday September 13, 1:00 PM Central US Time, via Teams.


Welcome to the Subscriptions Track of Connectathon 30!  This call will just be introductory information and an opportunity to ask questions.

All relevant content will be recorded and posted on YouTube.

Clinical Input Required?No
Related Tracks?

Testing Scenario:

System Roles

R4B FHIR Server

The FHIR Server supports the Subscription resource and related operations for the backport, as well as notifying subscribed clients of changes.

  • SHALL expose a Subscription resource supporting read, create and update.
  • SHALL expose a SubscriptionTopic resource supporting search and read.
    • MAY support SubscriptionTopic create, update, and delete.
    • MAY support notificationShape information (e.g., multiple resources)
  • SHALL perform notification distribution using the notification bundle on at least one of the following channel types:
    • REST-hook
    • Websockets
      • Servers supporting websockets SHALL support the $get-ws-binding-token operation
    • Email
  • SHALL expose a $status operation.
  • MAY expose a $events operation
    • MAY support content-type changing

We recommend that the servers support most of the core backport and at least one type of client (rest hook or web socket) before the connectathon starts in order to make the most out of the connectathon. You can do initial testing with the reference implementation:

R4B Subscribing client

Subscribes to FHIR server and gets updates.

  • SHOULD search or read SubscriptionTopic resource from the server.
  • SHALL create a Subscription instance on a FHIR server.
  • SHALL either:
    • expose an endpoint to accept notifications using REST-Hooks, or
    • use web sockets to receive notifications (requires support for calling the $get-ws-binding-token operation).
  • MAY use the $status operation to check/validate the status of a subscription
  • MAY use the $events operation to query for past events.

We recommend that the clients support creating subscriptions and a way to receive notifications  (rest hook or web socket) before the connectathon starts in order to make the most out of the connectathon. You can do initial testing with the reference implementation:


Subscription Creation

  • Action: A subscribing client creates a Subscription  for a SubscriptionTopic implemented by the server.
  • Precondition: An agreed upon topic must be supported by client and server
  • Success Criteria: The subscription exists and is in an active status. It includes all necessary fields in R5 and/or extensions in R4.
  • Bonus point: The subscribing client may update the Subscription status to off when it no longer needs the subscription (and server should honor).

Rest Hook Client Notification

  • Action: FHIR Server notifies Subscribing client by performing an HTTP/S POST to the endpoint identified in the subscription resource instance using the appropriate notification bundle.
  • Precondition: Create FHIR Subscription scenario
  • Success Criteria: FHIR server performs HTTP/S POSTs when the criteria in the Subscription is met within the FHIR server.

Websocket Client Notification

  • Action: Client is able to connect to a FHIR Server via WS/S, retrieve a token (via $get-ws-binding-token ), and receive notifications.  Server is able to provide all necessary operations for the Client, and send the appropriate notification bundles.
  • Precondition: Create FHIR Subscription scenario
  • Success Criteria: FHIR server sends notifications via websockets when the criteria in the Subscription is met within the FHIR server.

Security and Privacy Considerations

To be discussed prior to connectathon: Do we want to use the authorization header mechanisms to test authentication strategies?

Extended Scenarios / Discussions

  • Operation of R4 (4.0.1) Servers and Clients
  • Additional security for endpoints.
  • SubscriptionTopic creation / testing / documentation.