Fact Of Death Direct Enquiry Response Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Subscriptions

Subscriptions

FODDER supports asynchronous mortality notifications using the FHIR Subscriptions R5 Backport for R4 (topic-based subscriptions backported from R5 onto R4). A subscriber registers one or more patient identifiers of interest; when the FODDER service identifies a deceased patient matching any registered identifier, FODDER delivers an id-only notification to the subscriber's rest-hook endpoint, and the subscriber subsequently retrieves the matched Patient resource by id.

This page describes the topic, the Subscription profile, the registration flow, and the notification format.

Roles

• Subscriber — a system that wishes to be notified of mortality events for a known set of patient identifiers (e.g., a payer monitoring beneficiaries).
• FODDER server — the service that proxies queries to the Veritas Fact of Death API, publishes the SubscriptionTopic, accepts Subscription registrations, and delivers notifications.

Lifecycle

1. Register — Subscriber POSTs a Subscription (conforming to the FODDER Deceased Patient Subscription profile) to the FODDER server. Each patient identifier of interest is expressed as a separate filterBy criterion on the Subscription.criteria element.
2. Handshake / activate — The FODDER server moves the Subscription from requested to active after a handshake delivery to the subscriber's endpoint succeeds. (See the backport IG for handshake notification details.)
3. Notify — When the FODDER service confirms a mortality for a registered identifier, it delivers a notification Bundle to Subscription.channel.endpoint. The notification carries id-only payload — no Patient resource is included.
4. Retrieve — The subscriber issues GET Patient/{id} against the FODDER server (using the same OAuth client credentials), receives the FODDER Deceased Patient resource, and processes the mortality event.
5. End — The subscription terminates at Subscription.end, on subscriber-initiated DELETE, or after consecutive delivery failures (server-defined).

SubscriptionTopic

FODDER publishes a single SubscriptionTopic:

• Canonical: https://onyxhealth.io/fhir/fodder/SubscriptionTopic/deceased-patient-identified
• Resource: Patient
• Trigger: create or update of a Patient resource where Patient.deceased is a dateTime
• Filter parameter: identifier

​See the Deceased Patient Identified Topic artifact for the full definition.

Subscription profile

The FODDER Deceased Patient Subscription profile constrains the backport Subscription profile as follows:

filterCriteria syntax

Each filterCriteria extension carries a valueString of the form:

Patient?identifier=<system>|<value>

Multiple filterCriteria are combined as a logical OR — the subscriber is notified when a deceased Patient matches any of the listed identifiers. For example, to monitor two SSNs:

Patient?identifier=http://hl7.org/fhir/sid/us-ssn|123-45-6789
Patient?identifier=http://hl7.org/fhir/sid/us-ssn|987-65-4321

Notification format

Notifications are delivered as a Bundle of type = history. The first entry is a Parameters resource representing the SubscriptionStatus (the R4 backport equivalent of the R5 SubscriptionStatus resource). For id-only payload, subsequent entries carry only the fullUrl and request of each notified Patient — no resource body. See the Deceased Patient Notification Bundle Example.

Security

Subscription registration and notification delivery use the SMART on FHIR backend services flow (STU 2.2.0) — client_credentials grant with client_secret_basic or private_key_jwt authentication. Required scopes:

• system/Subscription.cruds — register, read, update, and delete Subscriptions
• system/Patient.rs — retrieve the Patient resource by id after a notification

The subscriber's rest-hook endpoint SHALL itself be protected (TLS, bearer token via Subscription.channel.header, mTLS, or equivalent). The id-only payload type is required by FODDER to minimize PHI in transit; no patient demographics are present in notification Bundles.

Example registration

POST /Subscription HTTP/1.1
Host: fodder.example.org
Authorization: Bearer <client-credentials-token>
Content-Type: application/fhir+json

{
  "resourceType": "Subscription",
  "meta": {
    "profile": [
      "https://onyxhealth.io/fhir/fodder/StructureDefinition/fodder-deceased-patient-subscription"
    ]
  },
  "status": "requested",
  "reason": "Mortality notification for monitored beneficiaries.",
  "criteria": "https://onyxhealth.io/fhir/fodder/SubscriptionTopic/deceased-patient-identified",
  "_criteria": {
    "extension": [
      {
        "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
        "valueString": "Patient?identifier=http://hl7.org/fhir/sid/us-ssn|123-45-6789"
      },
      {
        "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
        "valueString": "Patient?identifier=http://hl7.org/fhir/sid/us-ssn|987-65-4321"
      }
    ]
  },
  "channel": {
    "extension": [{
      "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
      "valueUnsignedInt": 86400
    }],
    "type": "rest-hook",
    "endpoint": "https://subscriber.example.org/fhir/notifications/fodder",
    "payload": "application/fhir+json",
    "_payload": {
      "extension": [{
        "url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
        "valueCode": "id-only"
      }]
    },
    "header": ["Authorization: Bearer <subscriber-rest-hook-token>"]
  },
  "end": "2027-04-26T00:00:00Z"
}

A complete worked example is provided in Subscription Example.

References

• FHIR Subscriptions R5 Backport (R4)
• FHIR R5 SubscriptionTopic
• FHIR R4 Subscription
• SMART App Launch STU 2.2.0 — Backend Services