10.3.1.1 | TTA Notifications (v0.4)

10.3.1.1 TTA Notifications

Version: 0.4

Introduction

This Technical Agreement (TA) describes and specifies the technical responsibilities to which parties agree when connecting to exchange transactions to facilitate notifications.

Notifications are a useful mechanism to support the information requirements of the receiver. It enables doctors, patients or system users to become aware of new data and changes in existing data as soon as they are registered.

This specification describes how organizations in Dutch healthcare exchange such notifications in a consistent and secure manner, defining the functional principles and the technical choices required for interoperable, implementable notification exchange. As a technical foundation, we use the FHIR R5 Subscription Framework, applied in R4 via the Subscriptions R5 Backport Implementation Guide (IG).

Context

The initial reason for drawing up this generic technical agreement is the need for a FHIR specification for the exchange of the BgZ (Basisgegevensset Zorg) between healthcare organizations in the context of a referral. The actual agreements for the exchange of the BgZ are provided in the BgZ attachment. The exchange of the BgZ is not the first use-case that requires a FHIR specification for the exchange of a set of FHIR resources between healthcare organizations in the context of a transfer of care. The eOverdracht information standard and corresponding TA cover a similar use-case and already provide a specification for the exchange of FHIR resources using a Notified Pull pattern. As such, the relevant specifications in the eOverdracht information standard and TA have served as a basis for this document. At some points this document deviates from the eOverdracht information standard and TA (most specifically in the exchange of the notification). Where it deviates, it does not aim to replace the existing version of the eOverdracht standards and corresponding implementations. It rather aims to provide a direction for the next iteration of the eOverdracht information standard and TA.

The scope of this TA however is not limited to these use cases. It sets guidelines for the use and specification of notifications in other existing and future exchange agreement, including those required by EHDS.

Scope

In scope:

• The exchange of notifications between healthcare provider organisations, including the payload mode used (see Notification Payload Model).

• The selection and coding of notification topics (SubscriptionTopic).

• The relationship with addressing (GF Addressing), authorization (GF Authorization), and patient consent (GF Toestemming/EHDS), without elaborating a specific addressing profile.

Exclusions (out of scope):

• Cancellation of FHIR notifications is not supported. FHIR notifications are stateless.

• Authentication and identification of the actors involved in the agreement (see TA I&A)

• The substantive pull that may follow a notification, where the notification itself does not carry the content (see TA Pull).

• The technical method by which consent is verified (see GF Toestemming and forthcoming EHDS regulation).

• The concrete registration, publication, and resolution of notification endpoints (see GF Addressing).

• Notifications that do not concern patient-related healthcare data exchange. The technical notification framework described in this TA may be used for these kind of notifications, but the patient-specific authorization, consent, privacy, and related governance requirements described herein do not apply.

Vocabulary

This TA uses several terms that carry a specific, technical meaning in FHIR distinct from their everyday English meaning. This section defines the terms this TA is built on.

• Notification — as used in this TA, a general term for the message sent from the Subscription Server to the Subscription Client when an event occurs. A notification is not a FHIR Resource type. Mechanically, a notification is a FHIR Bundle (type history for R4/R4B, per the Backport IG), whose first entry is a SubscriptionStatus (represented as a Parameters resource in the R4/R4B backport). See Notification Content.

• Subscription — a FHIR Resource representing a client’s registered request to be notified about a SubscriptionTopic, constrained for R4/R4B use by the Backport IG. Every notification is linked to an actual, registered Subscription resource; FHIR R4B does not support implicit Subscriptions.

• SubscriptionTopic — a FHIR Resource, introduced in FHIR R4B, defining the class of event a Subscription can register for: which resource type and interactions trigger it, and what a Subscription is allowed to filter on. SubscriptionTopics are defined in accordance with the FHIR R4B standard, and Subscriptions in accordance with the R4/R4B backport (there is no difference between R4 and R4B). SubscriptionTopics SHOULD be able to be communicated out-of-band. The practical consequence of the choice for version R4B is that a SubscriptionTopic can consist of only one FHIR resource type. This is because each Subscription is bound to exactly one SubscriptionTopic, and a SubscriptionTopic in FHIR R4B defines triggers and filters for a single resource type.

• notification-event.focus — the reference the Subscription Server places in a notification Bundle to identify the resource that triggered that specific event, i.e. the resource type the SubscriptionTopic monitors (see SubscriptionTopic). See Notification Payload Model for how this reference is used in id-only mode.

• canonical — a URL used as a stable, versionable identifier for a FHIR definitional resource (such as a SubscriptionTopic), as opposed to a normal resource reference, which points at a specific instance on a specific server.

• criteria — the Subscription.criteria element, which in the R4/R4B backport carries the canonical URL of the SubscriptionTopic a Subscription is bound to (via the backport-topic-canonical extension), not a free-text filter expression. Free-text-style scoping filters use the separate backport-filter-criteria extension instead.

Notification Payload Model

A notification’s channel.payload MAY carry one of the following content levels. The payload mode is requested per Subscription and MAY be accepted, modified, or rejected by the Subscription Server; this TA does not mandate one level for all use cases. A prior exchange agreement (e.g. a Referral or Transfer exchange agreement) MAY restrict which mode(s) may be used for a given SubscriptionTopic.

Rules:

• Sending a notification does not exempt the sender from the authorization and consent obligations that would otherwise apply to disclosing that same clinical content (see Privacy, Consent, and Authorization): a full-resource notification carries those obligations just as any other disclosure of the content would, and typically carries more of them than an id-only notification, since the content itself — not just a reference to it — leaves the sender’s system.

• Where neither a request nor an exchange agreement specifies a payload mode, id-only SHOULD be used: it keeps the notification to the minimum level of detail needed to identify what changed, without exposing clinical content on the channel itself.

Notification Patterns 

The Notified Pull exchange pattern applies to different models of medical record exchange.

Source Initiated Notifications
In a source initiated notification pattern, the sending healthcare provider determines that another healthcare provider should be informed when specific events occur. The sending organisation establishes and manages the notification relationship and sends notifications when relevant events occur.

Examples include referral or transfer updates and a specialist making a new consultation report available in the patient’s record.

Receiver Initiated Notifications
In a receiver initiated notification pattern, the receiving healthcare provider requests to be informed when specific events occur. The receiving organisation initiates the notification relationship and the sending organisation delivers notifications when relevant events occur.

Examples include laboratory result notifications and notification of changes to specific patient information. 

Quality and Privacy Considerations

Signal Fatigue and Specificity

A notification is an external trigger that can disrupt the receiver’s ongoing work, so how it is scoped and delivered matters. The immediate receiver of a notification is the Subscription Client — a system, not a person — which may in turn direct it to a human, such as a healthcare professional’s worklist or inbox. Signal fatigue can occur at either point: a system flooded with low-value notifications burns processing capacity and complicates prioritization, and a person flooded with low-value notifications starts to ignore them altogether, including the ones that matter. Too few notifications carries the opposite risk and can harm patient care. A SubscriptionTopic SHOULD therefore be scoped narrowly enough that the notifications it produces are relevant to the process they concern.
Great care SHOULD therefore be given to the specificity of notifications.

Privacy, Consent, and Authorization

Consent and authorization address different aspects of deciding whether data may be exchanged and are established through different mechanisms. Consent is the patient’s permission for their data to be exchanged for a given purpose. Authorization determines whether all applicable conditions for exchanging data are satisfied, including both the patient’s consent (where required) and whether a specific receiving party is entitled to receive notifications for a given SubscriptionTopic and patient. This TA delegates these determinations to GF Authorization and GF Patient Consent rather than defining them. A Subscription MUST NOT be activated, and a notification MUST NOT be sent, unless all applicable authorization and consent conditions are satisfied

Both payload modes require consent and authorization to have been established, but what they must cover differs (see Notification Payload Model):

• Empty / id-only notifications carry no clinical content, but are not privacy-neutral: the fact that a resource of a given type changed, tied to a specific patient (via the Subscription) and a specific care relationship between sender and receiver, is itself a thin disclosure about that patient’s record. This is the baseline privacy footprint of any notification under this TA. The Subscription Server MUST NOT activate a Subscription until patient consent has been verified (see Preconditions).

• Full-resource notifications carry clinical content directly and are subject to the same consent and authorization requirements as any other disclosure of that content — equivalent to a Push of the data itself. The exchange agreement selecting full-resource for a topic MUST establish that the applicable consent basis covers disclosure of that content to the receiver, not merely disclosure of the fact that it exists, and that basis MUST already be established at the moment a notification is sent — not deferred to a later point, since full-resource mode has no separate content-access step to defer it to.

In both cases, the Subscription Server MUST verify authorization and consent before a notification is sent (see Implementation Obligations).

Preconditions

This TA sets the following rules for the use of notifications and Subscriptions:

• All notifications and subscriptions (in-band and out-of-band) that are accepted MUST be well-defined by SubscriptionTopics agreed upon between all parties involved (binding to a topic canonical is required by R4B; the requirement that parties mutually agree the topic beforehand is added by this TA).

• All consent requirements specified by GF Toestemming/EHDS for the type of information disclosure associated with the Subscription's payload mode MUST be satisfied before a Subscription is activated (see Privacy, Consent, and Authorization).

• The receiver’s authorization to access the SubscriptionTopic and the patient data it concerns MUST be established via GF Authorization before a Subscription is activated (see Privacy, Consent, and Authorization).

• All endpoints MUST adhere to network Twiin security level standards: 10.4.7 | Network level security. Mutual TLS MUST be applied.

FHIR Technical Specification

Conformance

Implementations MUST conform to the HL7® FHIR® R4/R4B Subscriptions R5 Backport Implementation Guide. This TA repeats selected implementer obligations from that guide so that the required behavior can be understood without a detailed study of the Backport specification.

Sequence Diagram

The diagram below illustrates the technical flow of the Notified Pull notification pattern between the Subscription Client (receiving organisation) and the Subscription Server (sending organisation): subscription registration, handshake, recurring event/heartbeat notifications, and catch-up after a disruption. The actual content retrieval (the pull itself) is out of scope of this TA (see TA Pull).

A notification exchange between two organisations proceeds in a number of steps. Steps 1 and 2 are preparatory (once per subscription/topic); steps 3 and 4 are the operational steps that recur per event. Step 5 covers recovery after a missed notification or a channel outage.

Not every step and operation is required according to the R4B standard. We will specify those that are optional here.

1. Subscription registration.

On the sending organisation’s side, a Subscription is created for the receiving organisation, bound to a pre-agreed SubscriptionTopic. This agreement rests with the receiver: they want to be notified about this topic. How the Subscription is technically established can be determined per use case:

• in-band: POSTed by the Subscription Client itself; or

• out-of-band: set up by the Subscription Server based on a previously made agreement. For out-of-band subscriptions, the Subscription Client’s notification endpoint is looked up via GF Addressing (Endpoint.connectionType = hl7-fhir-rest, payloadType = Subscription).

Out-of-band Subscription creation is typically associated with the source initiated notification pattern, while in-band Subscription creation is typically associated with the receiver initiated notification pattern. These concepts are related but distinct: the notification pattern describes which party initiates the notification relationship, whereas in-band and out-of-band describe the technical mechanism used to establish the Subscription. 

2. Handshake

Immediately after registration, the Subscription Server MUST send a handshake-notification to the Subscription Client’s notification endpoint to confirm the channel; only a successful handshake sets Subscription.status to active.

For the rest-hook channel type, a handshake is mandatory: per the FHIR R4/R4B Subscriptions Backport IG, the Subscription Server SHALL set the initial Subscription.status to requested and SHALL update it to active only after a successful handshake-notification has been sent and accepted; any error in the handshake SHALL result in status being set to error.

3. Event notifications.

Whenever an event occurs on the Subscription Server’s side that matches the topic (and any applicable filter), the Subscription Server sends an event-notification Bundle. Each notification receives a monotonically increasing event-number so that the Subscription Client can detect missed notifications. The Bundle carries a focus reference (literal reference) to the source resource at the Subscription Server, and clinical content only if the Subscription’s payload mode is full-resource (see Notification Payload Model).

4. Heartbeats (if used).

At pre-agreed intervals, the Subscription Server sends a heartbeat-notification so that the Subscription Client can detect a channel outage, even when no events are actually occurring (see Heartbeat Notification for whether this applies to a given Subscription).

5. Catch-up after disruption.

When the Subscription Client detects a gap in the event-number sequence or a missing expected heartbeat, it uses the $events and $status operations on the Subscription at the Subscription Server to retrieve missed notifications or verify the Subscription status.

The $status operation informs the Subscription Client of the state of the subscription. The Subscription Server MUST support this operation.

The $events operation asks the server to replay past notifications. Subscription Servers MAY support this operation; support is not required.

6. Follow up on notification

The receiver can subsequently retrieve the content behind the focus reference via the sender’s FHIR endpoint. The content pull and associated access control fall outside this specification (see GF’s Identification, Authentication, Authorisation, Consent and the TA Pull).

System Roles and Responsibilities

Subscription Server
The Subscription Server runs on the sending organisation’s side and is responsible for managing Subscriptions and delivering notifications. The Subscription Server MUST:

• Create Subscription resources for the agreed SubscriptionTopic(s) (based on pre-agreed topics or as a result of a Subscription Client requesting a subscription);

• Send event-notification Bundles in which event-number is incremented in a concurrency-safe manner;

• Support the $status operation on the Subscription, as well as read and search with search parameters status, criteria, channel.endpoint, channel.type, and channel.payload;

• Verify before each send that a valid Subscription exists for this receiver, that the receiver is authorized (via GF Authorization) to receive notifications for the SubscriptionTopic and patient involved, and that the consent conditions for the patient involved have been met (see Privacy, Consent, and Authorization).

• Support the creation of Subscriptions by Subscription Clients (in-band managed Subscriptions), accepting only Subscriptions for pre-agreed SubscriptionTopics.

• Send handshake-notification Bundles when Subscription.status is set to requested (with retry), and update Subscription.status accordingly;

The Subscription Server MAY:

• Support the $events operation on the Subscription.

• Send heartbeat-notification Bundles at established intervals (with retry), where agreed for the Subscription (see Heartbeat Notification);

Subscription Client

The Subscription Client runs on the receiving organisation’s side and consumes notifications. The Subscription Client MUST:

• Receive notification Bundles at the notification endpoint and forward them internally to the processing system;

• Accept handshake-notification Bundles at the notification endpoint, since Subscription.status cannot become active until this succeeds (see Handshake Notification).

• Check every incoming Bundle for continuity, using the highest processed event-number; missed notifications may be retrieved via the $events operation at the Subscription Server;

The Subscription Client MAY:

• Check at agreed intervals whether a heartbeat-notification has been missed, where heartbeat is used for the Subscription (see Heartbeat Notification); if so, the Subscription status SHOULD be queried via $status.

• Create Subscription resources on its own initiative for the agreed SubscriptionTopic(s) at a Subscription Server.

The Subscription Client is responsible for signalling and recovering from faulty communication, and SHOULD therefore keep track of the state of its Subscriptions.

Implementation Obligations

• Logging. Both parties MUST log notification sends and receipts — including handshake, and heartbeat where used — with enough detail to reconstruct, after the fact, which notifications were sent, received, or missed for a given Subscription. This is not addressed by the Backport IG, and is required by this TA to support incident investigation and to substantiate that the authorization and consent verifications below were actually performed at the time a notification was sent, not only that a rule requiring them exists.

• Authorization verification. The Subscription Server MUST verify, before activating a Subscription and again immediately before each notification send, that the receiver is authorized (via GF Authorization) to receive notifications for the SubscriptionTopic and patient involved. This is independent of, and in addition to, the consent verification below — authorization can be withdrawn or expire on its own timeline, separate from patient consent.

• Consent verification. The Subscription Server MUST verify, immediately before each notification send, that the consent conditions applicable to that payload mode (see Privacy, Consent, and Authorization) are still met — not only at Subscription creation time. Consent MAY be withdrawn after a Subscription is created; the server is responsible for reflecting that at send time.

Transactions

The transactions below take place between the Subscription Server and the Subscription Client over an mTLS-secured channel (see Preconditions). The wire format and behavioural details follow the Subscriptions R5 Backport for R4; below we limit ourselves to the requirements that are additional or more restrictive in this context.

Creating a Subscription

A Subscription is created on the sender’s side. This happens either out-of-band (the sender sets up the Subscription based on a notification endpoint obtained from the receiver via GF Addressing, having verified via GF Authorization that the receiver is entitled to receive notifications for this SubscriptionTopic) or in-band (the receiver POSTs a Subscription to the Subscription Server, which verifies the same authorization before accepting it). A Subscription:

A Subscription is intended as a long-running agreement between the Subscription Server and Subscription Client about a topic, not as a per-event object.

Use Case Roles

Referenced Standards

• HL7® FHIR® R4/R4B — Subscriptions R5 Backport Implementation Guide

• GF Addressing (for out-of-band endpoint resolution)

• HTTPS over mTLS

Messages

Request message

Trigger: A receiving organisation (or the sender, on its behalf, out-of-band) wants to be notified about a pre-agreed SubscriptionTopic.

Description: The Subscription carries the SubscriptionTopic canonical (extension backport-topic-canonical) on Subscription.criteria, optionally a scoping filter (backport-filter-criteria), channel.type = rest-hook with the Subscription Client’s notification endpoint, and channel.payload = application/fhir+json with extension backport-payload-content set per the payload mode agreed for that Subscription (see Notification Payload Model).

Technical Details:

Response message

Description: The Subscription Server accepts or rejects the Subscription and (if accepted) sets its status, after which the handshake transaction follows.

Technical Details:

Payload: On success: the created Subscription resource (201 Created). On error: a FHIR OperationOutcome with details.

Rules

A Subscription

• MUST carry a pre-agreed SubscriptionTopic canonical on Subscription.criteria via the extension backport-topic-canonical;

• MAY carry a scoping filter via the extension backport-filter-criteria;

• MUST set Subscription.channel.type = rest-hook with the Subscription Client’s notification endpoint. R4B allows a server to support any channel type it chooses (rest-hook, websocket, email, message); this TA restricts the channel type to rest-hook;

• MUST set Subscription.channel.payload = application/fhir+json and the extension backport-payload-content per the payload mode agreed for that Subscription (see Notification Payload Model and Notification Content);

• MUST be set to active only after a successful handshake (see Handshake Notification), and set to off (not deleted) upon retirement.

Additional Notes

• Subscriptions can contain only one resource type (R4B SubscriptionTopic constraint).

Handshake Notification

After a Subscription is created, the Subscription Server sends a handshake-notification Bundle to the Subscription Client’s notification endpoint. On success, Subscription.status is set to active; on failure, retries MUST be attempted with exponential backoff, and on persistent failure the status is set to error.

Use Case Roles

Referenced Standards

• HL7® FHIR® R4/R4B — Subscriptions R5 Backport Implementation Guide

• HTTPS over mTLS

Messages

Request message

Trigger: The Subscription Server has accepted a new Subscription and its status is requested.

Description: The Subscription Server sends a handshake-notification Bundle (type = handshake-notification) to the Subscription Client’s notification endpoint to confirm reachability, with retry on failure using exponential backoff (R4B only permits retry, without specifying a strategy; the exponential-backoff strategy itself is required by this TA).

Technical Details:

Response message

Description: On success, the Subscription Server sets Subscription.status to active; on persistent failure, status is set to error.

Technical Details:

Payload: Typically empty (200 OK); on error, a FHIR OperationOutcome.

Additional Notes

• This resource does not need to be stored persistently by the receiver beyond updating its own Subscription state.

Event Notification

For each event matching the topic and filter, the Subscription Server sends one event-notification Bundle to the Subscription Client’s notification endpoint. The Bundle:

Use Case Roles

Referenced Standards

• HL7® FHIR® R4/R4B — Subscriptions R5 Backport Implementation Guide

Messages

Request message

Trigger: An event occurs at the Subscription Server matching the active Subscription’s topic and filter criteria.

Description: The Subscription Server sends an event-notification Bundle (type = event-notification) carrying a monotonically increasing event-number (assigned in a concurrency-safe manner) and a notification-event.focus reference to the source resource. The Bundle MUST NOT carry clinical content beyond what the SubscriptionTopic’s selected payload mode permits (see Notification Payload Model).

Technical Details:

Response message

Description: The receiver acknowledges receipt and, if it wishes to access the content, performs a separate, authorised pull via the sender’s FHIR endpoint (out of scope of this TA, see TA Pull).

Technical Details:

Payload: Typically empty (200 OK).

Rules

A notification

• MUST carry a monotonically increasing event-number, assigned in a concurrency-safe manner;

• MUST carry a notification-event.focus referencing the source resource at the Subscription Server;

• MUST NOT carry clinical content beyond what the SubscriptionTopic’s selected payload mode permits (see Notification Payload Model and Notification Content).

Additional Notes

• Processing MUST be idempotent: re-delivering the same event-number MUST NOT cause duplicate side effects (not addressed by R4B; required by this TA).

• Content access following the focus reference is reassessed for authorisation at the moment of access.

Heartbeat Notification (Optional)

At pre-agreed intervals, the Subscription Server sends a heartbeat-notification Bundle. This serves as a keep-alive signal for the channel and allows the Subscription Client to detect a silent outage even when no events are occurring.

Per FHIR R4B, whether heartbeats are used is settled through a request/accept mechanism at Subscription creation: the Subscription Client requests a heartbeat interval (via the backport-heartbeat-period extension on Subscription.channel), and the Subscription Server MAY accept that request as given, modify it, or omit heartbeats altogether. A prior agreement between the parties MAY restrict this mechanism — for example, by fixing the interval in advance or ruling out heartbeats entirely, or requiring the Subscription Server to support and accept heartbeat requests.

For out-of-band Subscriptions, the request/accept mechanism above does not apply, because there is no live request from the Subscription Client: the Subscription Server creates the Subscription unilaterally. Whether heartbeats are used, and at what interval, must therefore be settled entirely by the prior agreement between the parties, and the Subscription Server sets the heartbeat interval on the Subscription it creates accordingly.

The value of using heartbeats depends on the notification pattern being used.

Heartbeats provide assurance at two levels simultaneously: they verify that the technical communication path is functioning, and that the specific FHIR subscription contract remains active and operational.

For source initiated notifications, the sending organisation controls and verifies the establishment of the notification channel itself, so only the first assurance (technical path) is needed, and retries provide an alternative for this. Heartbeats are therefore less valuable for source initiated notifications.

For receiver initiated notifications, heartbeats provide valuable confirmation that the Subscription remains active and that the notification service continues to operate as expected.

Use Case Roles

Referenced Standards

• HL7® FHIR® R4/R4B — Subscriptions R5 Backport Implementation Guide

Messages

Request message

Trigger: The pre-agreed heartbeat interval for an active Subscription elapses.

Description: The Subscription Server sends a heartbeat-notification Bundle (type = heartbeat-notification) as a keep-alive signal for the channel.

Technical Details:

Response message

Description: The receiver resets its missed-heartbeat timer; if a heartbeat is missed, the receiver SHOULD query $status.

Technical Details:

Payload: Typically empty (200 OK).

Additional Notes

• Heartbeat sending is optional per Subscription, agreed at creation time.

$status and $events Operations ($events Optional)

The receiver uses:

• $status to query the current state of a Subscription at the Subscription Server — typically after a missed heartbeat;

• $events to retrieve a specific event-number or a range thereof — typically after detecting a gap in the sequence.

Use Case Roles

Referenced Standards

• HL7® FHIR® R4/R4B — Subscriptions R5 Backport Implementation Guide (GET [base]/Subscription/[id]/$status and $events operations)

Messages

Request message

Trigger: The receiver detects a gap in the event-number sequence, or a missing expected heartbeat.

Description: The Subscription Client invokes $status to query the current state of the Subscription, or $events to retrieve a specific event-number or range thereof.

Technical Details:

Response message

Description: The Subscription Server returns the current SubscriptionStatus, or replays the requested event-notification(s).

Technical Details:

Payload: On success: a SubscriptionStatus Parameters resource (status) or one or more notification-event Bundles (event). On error: a FHIR OperationOutcome.

Additional Notes

• Used for recovery only; not part of the regular operational flow.

• Temporary agreement: retention period for replayable events is to be agreed per use case.

Error Handling

All transactions MUST return a FHIR OperationOutcome with an appropriate HTTP status code in case of errors (R4B does not mandate an OperationOutcome on every error path; this is required by this TA). Clients MUST retry transient errors (5xx, network errors) with exponential backoff (R4B only permits retry without specifying a strategy; this TA requires exponential backoff specifically). Processing MUST be idempotent: re-delivering a previously processed notification MUST NOT cause duplicate side effects (not addressed by R4B; required by this TA).

Notification Content

Notification

A notification is a FHIR Bundle of type history, conforming to the Backport profile backport-subscription-notification. The Bundle contains a Parameters resource (SubscriptionStatus, conforming to backport-subscription-status-r4) with at least:

• subscription — reference to the registered Subscription;

• status — active or off;

• type — event-notification, handshake-notification, or heartbeat-notification;

• notification-event.event-number — monotonically increasing number to detect missed events;

• notification-event.timestamp — the moment the event occurred at the Subscription Server;

• notification-event.focus — reference to the source resource to which the event relates.

The remainder of the Bundle’s content depends on the Subscription’s payload mode (see Notification Payload Model for what each mode is and why an exchange agreement would choose it):

Id-only mode. The Bundle carries the notification-event.focus reference and no further clinical content. Compared to a notification without a resource reference at all, this has a clear operational advantage: without a reference, the receiver would have to search within the topic itself to determine which change corresponds to the notification — ambiguous when multiple resources change in quick succession, and it burdens both sender and receiver with extra queries. With id-only, it is immediately clear what the notification refers to, while the content itself is still only retrieved via an authorised pull.

Full-resource mode. The Bundle additionally carries the resource content itself, so no separate pull is required to access it (see Privacy, Consent, and Authorization for the consent and authorization basis this requires at send time).

Empty mode. The Bundle carries none of the identifying fields above beyond what is needed to associate the notification with a Subscription; it signals only that a matching event occurred for a specific Subscription.

SubscriptionTopic

A SubscriptionTopic defines the events for which notifications are sent. Key properties are:

• SubscriptionTopic.url - The unique name of the topic

• resourceTrigger.resource and SubscriptionTopic.resource — the resource type the topic monitors (e.g. Task or Observation)

• resourceTrigger.supportedInteraction — which interactions trigger it (e.g. create, update)

• canFilterBy — which fields a Subscription may filter on (e.g. Task.owner, Task.for, or Observation.code, Observation.subject)

• queryCriteria — optional further narrowing using coded criteria (e.g. a SNOMED procedure code to specialise a generic Task topic for transfer-of-care use cases, or a generic Observation topic for a specific lab test)

Subscription

A Subscription is the FHIR resource that models a long-running agreement between a Subscription Server (sender) and a Subscription Client (receiver) about which notifications should be delivered, and where. When created in-band, the content MUST adhere to these rules:

• MUST be bound to exactly one pre-agreed SubscriptionTopic, referenced via Subscription.criteria using the extension backport-topic-canonical.

• MAY carry a scoping filter via the extension backport-filter-criteria to narrow which events qualify (e.g. filter by Task.owner or Observation.code).

• channel.type MUST be rest-hook, pointing at the Subscription Client’s notification endpoint. (R4B allows a server to support any channel type it chooses — rest-hook, websocket, email, message; this TA restricts the channel type to rest-hook.)

• channel.payload MUST be application/fhir+json, with the extension backport-payload-content set to the payload mode agreed for the Subscription (empty, id-only, or full-resource — see Notification Payload Model).

Changes from version v0.3

• Removed the out-of-scope declaration of routing. As routing is not applicable to notification.

• Removed the rule stating that parties must agree on the payload mode per SubscriptionTopic and that this MUST NOT be negotiated per-Subscription. The original statement did not conform to Backport R4B

• Expanded “that a matching event occurred” to “that a matching event occurred for a specific Subscription”

• Updated the Subscription item in the Vocabulary section to reflect that every notification is linked to an actual, registered Subscription resource, since FHIR R4B does not support implicit Subscriptions.

• Examples in SubscriptionTopic section are no longer workflow specific.

• Workflow-related Notifications section removed

• Vocabulary references to Task, Task.intent and Task.focus removed

• Source Initiated Notifications examples are changed and clarified.

• Sentence describing disruptive nature of notifications clarified.

• ‘The Subscription Server MUST NOT activate a Subscription until patient consent has been recorded’ replaced ‘The Subscription Server MUST NOT activate a Subscription until patient consent has been verified’

• Receiver and Sender replaced with Subscription Client and Subscription Server where applicable

• The heartbeat sections wrongly described heartbeat actions. This sentence has been moved.

• $event replaced by $events

• Handshake is no longer optional, as FHIR R4B requires it for REST-hook-channel.

• ‘The privacy and consent implications of a notification depend on its payload mode’ suggested consent would not be required for certain payloads. This is now clarified.

• The original document used the term consent registration where consent verification was meant. This corrected.

• The original document gave no clear description of the support requirements regarding heartbeats. This is now clarified by referring to the request/accept mechanism specified in FHIR R4B.

• The whole Notification Patterns and Optional Features section is removed, as handshakes are no longer optional. The heartbeat specific section is moved to the Heartbeat Notification section.

• Changed the requirement that payload mode be selected and fixed per SubscriptionTopic via a mandatory exchange agreement, restoring per-Subscription selection: the payload mode is now requested per Subscription.

• Replace the hard rule on defaulting to id-only with a reasoned argument why it is often preferable.