Subscription — Real-time FHIR subscriptions

R5 rewrote Subscription around the topic concept. No more search-string criteria — instead reusable SubscriptionTopics, for reliable, declarative, auditable notifications.

Purpose

Subscription describes a subscription to a FHIR event stream: creation, update or deletion of resources matching a topic. R5 replaced the old R4 criteria (search string) with SubscriptionTopics referenced via canonical: topics are defined once on the server or in an IG and reused by every Subscription.

When an event matches an active Subscription, the server sends a notification on the requested channel (channelType): REST hook (webhook), email, SMS, WebSocket, FHIR message.

Key fields

Supported channels

• rest-hook — HTTPS POST to endpoint. The most common.
• websocket — persistent WebSocket connection.
• email — email to endpoint.
• sms — SMS to endpoint number.
• message — FHIR Bundle type=message to endpoint.

JSON example

Subscription to Cardiology service admissions, delivery via REST hook with Bearer token:

{
  "resourceType": "Subscription",
  "id": "admission-monitor",
  "status": "active",
  "topic": "http://example.org/SubscriptionTopic/admission",
  "reason": "Real-time monitoring of Cardiology service admissions",
  "end": "2026-12-31T23:59:59Z",
  "managingEntity": { "reference": "Organization/hospital-1" },
  "contact": [{
    "system": "email",
    "value": "ops@hospital-1.example.org"
  }],
  "filterBy": [{
    "resourceType": "Encounter",
    "filterParameter": "class",
    "comparator": "eq",
    "value": "IMP"
  }, {
    "resourceType": "Encounter",
    "filterParameter": "service-provider",
    "comparator": "eq",
    "value": "Organization/cardiology-dept"
  }],
  "channelType": {
    "system": "http://terminology.hl7.org/CodeSystem/subscription-channel-type",
    "code": "rest-hook"
  },
  "endpoint": "https://app.example.org/fhir/subscriptions/notify",
  "parameter": [{
    "name": "Authorization",
    "value": "Bearer eyJhbGciOiJSUzI1NiIs..."
  }],
  "heartbeatPeriod": 60,
  "timeout": 30,
  "contentType": "application/fhir+json",
  "content": "id-only",
  "maxCount": 20
}

Common pitfalls

• No topic — R5 requires a canonical SubscriptionTopic. The old R4 criteria are not supported without backport.
• Non-HTTPS endpoint — strongly discouraged: notifications carry patient data.
• No contact — if the endpoint stops answering, the server flips Subscription to status=error and tries to notify contact[].
• Unbounded volume — without strict maxCount and filterBy, a Subscription can generate thousands of notifications/hour.
• content=full-resource on sensitive data — prefer id-only and let the client GET the resource via OAuth for traceability.

Related resources

• SubscriptionTopic — definition of the subscribed topic.
• SubscriptionStatus — state of a delivery (handshake, heartbeat, event-notification).
• Bundle — notification format (type=subscription-notification).
• CapabilityStatement — declares supported channels.