FHIR R5 Subscription replaced R4's per-endpoint criteria-and-hook model with a topic-based model where multiple subscribers reference shared SubscriptionTopic definitions. This scales much better in production; understanding the model matters for anyone building event-driven FHIR integrations.
SubscriptionTopic structure
A SubscriptionTopic defines: resourceTrigger (what change fires the topic), notificationShape (which fields ride the notification), and canFilterBy (filter parameters subscribers can use). Once defined, multiple Subscription resources reference the topic and receive notifications matching their filters.
Backport for R4B
Many R4B server implementations backport SubscriptionTopic. Check the server's CapabilityStatement.rest.resource.searchInclude for topic support before deploying. HAPI FHIR, Aidbox, and Medplum all support the R4B backport.
Delivery channels
- rest-hook — POST to a URL. Most common, requires the subscriber to be reachable. - websocket — persistent connection for real-time apps. - message — publish to a message queue (Kafka, SNS).
Rest-hook is the default; message channel is what scales for multi-tenant deployments.
Reliability considerations
1. Retry semantics — notification delivery should retry with exponential backoff. Server support varies; verify before deploy. 2. Dead-letter handling — subscriptions that fail delivery >N times should be paused or notified. 3. Back-pressure — a slow subscriber shouldn't block the FHIR write path. Buffered queue between server and subscriber is required.
Vendor support (mid-2026)
| Server | SubscriptionTopic | Rest-hook retry | Dead-letter | Message channel |
|---|---|---|---|---|
| HAPI JPA 7.x | Yes | Manual | Manual | External |
| Aidbox 2409 | Yes | Built-in | Built-in | Native |
| Medplum 3.x | Yes | Built-in | Built-in | Bots (native) |
| Microsoft FHIR Server | Partial | Add-on | Add-on | Add-on |
Migration from R4 Subscription
R4 Subscription resources continue to work on R5-capable servers; new subscriptions should use SubscriptionTopic. No forced migration, but new patterns should use the new model.