SubscriptionStatus
The current status of a FHIR Subscription: events emitted, last sequence numbers, status. The notification payload type=handshake / heartbeat / event-notification.
Purpose
SubscriptionStatus is the notification body sent by the FHIR server to subscribers via WebSocket, REST hook, email or message. It indicates the current subscription status (initial handshake, liveness heartbeat, event notification, query-event) and carries the resources tied to the triggering event. It is the modern (R4B/R5) counterpart of the historical FHIR R4 Subscription.
Key elements
| Field | Type | Cardinality | Role |
|---|---|---|---|
status | code | 0..1 | `requested`, `active`, `error`, `off`, `entered-in-error`. |
type | code | 1..1 | `handshake`, `heartbeat`, `event-notification`, `query-status`, `query-event`. |
eventsSinceSubscriptionStart | integer64 | 0..1 | Total events since start. |
notificationEvent | BackboneElement[] | 0..* | List of conveyed events. |
subscription | Reference(Subscription) | 1..1 | Linked Subscription. |
topic | canonical(SubscriptionTopic) | 0..1 | Subscribed topic. |
error | CodeableConcept[] | 0..* | Detected errors. |
JSON example
{
"resourceType": "SubscriptionStatus",
"id": "example-event-notif",
"status": "active",
"type": "event-notification",
"eventsSinceSubscriptionStart": 247,
"notificationEvent": [{
"eventNumber": 247,
"timestamp": "2026-05-15T17:30:00+00:00",
"focus": {
"reference": "Encounter/encounter-001"
}
}],
"subscription": {
"reference": "Subscription/example-sub-001"
},
"topic": "https://example.org/fhir/SubscriptionTopic/admission-discharge"
}Common pitfalls
- Type=event-notification without notificationEvent: empty payload.
- EventsSinceSubscriptionStart non-monotonic: server has lost events.
- Status='error' without error: impossible to diagnose.
Related resources
- subscription — subscription.
- subscriptiontopic — event topic.
- auditevent — audit log.
- messageheader — FHIR Messaging event.