Close
Search

Notifications

NB: This is a draft specification!

The notified-pull pattern requires the data provider to send a notification to the data consumer. This means that ZorgDomein will send a notification to the recipient of a transaction when new data is available for the recipient. It also means that ZorgDomein expects a notification from the initiator of a transaction as soon as the initiator has new data available for a transaction.

Notifications and FHIR

The specifications of the notification should preferably match any specification for notifications in the FHIR standard. The only part of the FHIR standard that specifies requirements for notifications is the FHIR subscription mechanism, see https://www.hl7.org/fhir/STU3/subscription.html#channels. The main advantage of conforming to these specs, is that it enables future implementations of a subscription mechanism. The FHIR specs mention five different notification channels (REST hook, web socket, e-mail, sms, and FHIR messaging). ZorgDomein Integrator will only support the REST hook channel. According to the specification, a REST Hook notification is implemented as “an empty POST message to alert the subscriber that new results are available”. Additional headers may be supplied in the HTTP POST request.

When a data consumer receives a notification, it must be able to extract the following parameters from the notification in order to be able to act on the notification:

  • Notification scope: the data consumer must know what type of data is published by data provider, so that it can generate a specific query to collect that data from the data provider.
  • Notification sender: the data consumer must know to who sent the notification, so that it knows where to collect the data.
  • Notification recipient: the data consumer must know who the recipient of the notification is, so that it can present that recipient at the data provider when collecting the data. This enables the data provider to authenticate the recipient. This is especially important when one consuming application is shared by multiple recipients (e.g. for SaaS systems).

Notification scope

The scope of the notification is defined by the url to which the notification is sent. This url follows the following schema:

[baseNotificationEndpoint]/[ResourceType]/[ResourceIdAtDataProvider]

The elements of the notification url can be used by the data consumer to generate a FHIR request to obtain the data at the data provider. Since the notification url includes both the FHIR resource type and resource id, this tells the data consumer that there is a specific FHIR resource available at the data provider. To request that resource, the data consumer should send the following FHIR read request to the data provider:

GET [FhirServerUrl]/[ResourceType]/[ResourceIdAtDataProvider]

Identification of notification sender and recipient

Both the notification sender and the recipient should be included in a JSON web token (JWT) that is submitted with the notification in the HTTP Authorization Bearer header of the POST request. See RFC 7519 and jwt.io for a detailed specification of JSON web tokens.

The claims in the header of the JWT must conform to the following specifications:

  • typ: JWT (fixed value)
  • alg: one of PS256, PS384, PS512, ES256, ES384 or ES512 (fixed value)
  • x5c: Contains the X.509 public key certificate corresponding to the key used to digitally sign the token. To limit token size, this must be a single certificate that has been issued by a PKIoverheid Private Services CA (G1). Does not apply to Nuts compliant interfaces.
  • kid: contains the identifier of a key published in the custodian’s DID document. Only applies to Nuts-compliant interfaces.

The claim in the payload of the JWT must conform to the following specifications:

  • iss: Identifier of the healthcare organization that sends the notification. For Nuts compliant interfaces this claim must contain the DID of the custodian/authorizer. For other interfaces this claim must contain the identifier of the healthcare organization that was exchanged during activation of the interface for that healthcare organization. For notifications that ZorgDomein receives, the value of this claim is used in subsequent access token requests.
  • sub: Identifier of the healthcare organization that receives the notification. For Nuts-compliant interfaces this claim must always contain the DID of the actor/requester. For other interfaces this claim must contain the identifier of the healthcare organization that was exchanged during activation of the interface for that healthcare organization.
  • aud: Base url of the notification service of the data consumer. For Nuts-compliant interfaces this claim must always contain the DID of the custodian’s notification service url.
  • practitioner_id: Identifier of the healthcare practitioner if the recipient is a practitioner.
  • patient_id: Identifier of the patient for whom data is exchanged (optional). ZorgDomein will not provide this id in notifications but is able to extract this id from notifications and use it in subsequent access token requests.
  • jti: Unique identifier of the token.
  • iat: Token creation timestamp.
  • exp: Token expiration timestamp.

The JWT must be signed using the signing algorithm specified in the alg claim of the token header and the key pair corresponding to the kid claim or the certificate in the x5c claim. The recipient of the notification must validate the token using the certificate provided in the x5c claim or using the public key referenced by the kid claim for Nuts-compliant interfaces. The certificate provided in the x5c claim must have been issued by a PKIoverheid Private Services CA (G1).

Notification response

The following rules apply to the notification response that is sent by the data consumer:

  • If the data consumer is able to process the notification correctly, is must return an empty HTTP 202 response.
  • If the data consumer receives a notification with an unknown or invalid path, it must return an empty HTTP 404 response.
  • If the JWT in the notification header is missing, malformed or invalid, the data consumer must return an empty HTTP 401 response.
  • If the JWT in the notification header is valid, but the notification sender is not authorized by the data consumer to access its notification endpoint, it must return an empty HTTP 403 response.
  • If the data consumer fails to process the notification due to an internal error, it must return an empty HTTP 500 response. In that case the data provider must try to resend the notification.