For FHIR R4 (channel-based): POST a Subscription resource with criteria (a search query string like 'Observation?patient=123'), channel.type (rest-hook, websocket, email, or sms), and channel.endpoint pointing to your webhook URL.
For FHIR R4B/R5 (topic-based): POST a Subscription resource referencing a SubscriptionTopic by canonical URL in the topic field; the SubscriptionTopic defines the trigger logic server-side rather than embedding a query in the Subscription.
For rest-hook subscriptions, expose an HTTPS endpoint that accepts POST requests; some servers send a handshake payload on subscription activation that you must acknowledge with a 200 response.
Handle incoming notification payloads: R4 rest-hook sends an empty Bundle or the changed resource depending on server implementation; R4B/R5 sends a structured notification Bundle with event details.
To retrieve the full resource after a notification, use the ids or full URLs provided in the notification Bundle to make a standard FHIR read request.
Implement idempotent notification handling using the notification's event number or resource version to tolerate duplicate deliveries.
Known gotchas
R4 Subscription criteria are evaluated differently across servers—some evaluate on write, some on a polling schedule; do not assume sub-second delivery latency for time-sensitive workflows.
The R4 and R4B/R5 Subscription models are not backward compatible; a Subscription resource valid in R4 is structurally different from one in R5, and servers will reject the wrong format.
Rest-hook endpoint URLs must be reachable from the FHIR server's network; firewalls, private VPCs, or localhost URLs will silently fail subscription delivery.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp