Implement a FHIR Subscription using an email or websocket channel type and handle the subscription handshake and heartbeat to maintain an active real-time notification connection
domain: hl7.org/fhir/uv/subscriptions-backport · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Create a Subscription resource with channel.type=websocket and no endpoint URL; retrieve the websocket connection URL from the server after creation
Connect to the websocket URL using a WebSocket client; receive the initial handshake notification Bundle with notificationType=handshake to confirm the connection is active
Process heartbeat notification Bundles (notificationType=heartbeat) sent at the configured heartbeatPeriod interval; use these to detect dropped connections and reconnect
Receive event notification Bundles (notificationType=event-notification) containing the resource reference or full resource depending on the Subscription content setting
On reconnection, use GET /Subscription/{id}/\$events with the _sinceEventNumber parameter to retrieve any missed events during the disconnection window
Known gotchas
Websocket channel support is optional in the backport IG and rarely implemented in production; REST-hook channels are far more widely supported for production notification workflows
The $events operation for backfilling missed events requires the server to retain an event log; servers are not required to retain events indefinitely, so gaps in event history are possible after a long disconnection
Heartbeat Bundles do not contain clinical data and should not be processed as event notifications; distinguish them by checking SubscriptionStatus.notificationType before parsing the notificationEvent array
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?