Publish Box goes here

Subscriber Role Integration

Subscriber Role Integration

Use the subscriber adapter role when your organization processes care data, but the receiving system does not implement FHIR Subscription notifications or notified pull.

In this role, the adapter sits between an external source adapter and the internal processing system.

processing system
  -> simple subscribe request
subscriber adapter
  -> FHIR Subscription request and notification handling
source adapter

Responsibilities

The subscriber adapter role is responsible for:

• turning a simple local subscription request into a FHIR R4 Subscription Backport request;
• receiving handshake and event notifications;
• parsing notification bundles;
• finding the related-query;
• executing the pull;
• storing or exposing the pulled event data to the local processing system.

The receiving or processing system is responsible for:

• deciding which topic and patient it wants to follow;
• consuming the pulled data;
• applying its own business process;
• storing any local copies it is allowed to store;
• handling user-facing workflow, triage or analytics.

The receiving system does not need to parse Backport Bundle or Parameters resources.

Minimum Integration Contract

The receiving system requests a subscription through a simple local call:

POST /subscriber/internal/subscriptions
Content-Type: application/json

{
  "topic": "https://fhir.cumuluz.org/subscription-topic/heart-failure-daily-check",
  "patientId": "hf-patient-001",
  "content": "empty"
}

The subscriber adapter turns this into a FHIR R4 Subscription and sends it to the source adapter. The source adapter performs the handshake. After the handshake, the subscription is active.

Receiving Event Data

When the source adapter sends an event notification, the subscriber adapter:

1. receives the REST-hook notification;
2. extracts the subscription id, notification type, focus and related query;
3. calls the related query;
4. receives a FHIR searchset Bundle;
5. exposes the pulled resources to the receiving system.

In the prototype UI, the subscriber inbox shows:

• notification type;
• patient chip;
• information types;
• pulled resource references;
• full FHIR JSON for inspection.

Idempotent Subscription Requests

The subscriber side may retry a subscription request. The source adapter deduplicates by endpoint, topic and patient. Retrying the same request returns the existing subscription and does not create a second active subscription.

For the local receiving system this means it is safe to call the subscribe endpoint during startup or recovery, as long as it uses a stable callback endpoint and the same patient/topic scope.

Production Considerations

A production subscriber adapter must add:

• endpoint identity and mutual authentication;
• durable inbox and pull result storage;
• retry handling when pull fails;
• replay support;
• validation of notification source;
• mapping from pulled FHIR resources to local processing models;
• monitoring for missed events and stale subscriptions;
• explicit handling for subscription deletion or renewal.