Define or discover available SubscriptionTopic resources on the FHIR R5 server: GET /SubscriptionTopic to list all topics; each SubscriptionTopic defines the resource trigger (e.g., Observation creation), optional query criteria, and allowed filter parameters
Create a Subscription resource: set Subscription.topic to the canonical URL of the desired SubscriptionTopic, Subscription.channelType to 'rest-hook', and Subscription.endpoint to your HTTPS webhook URL
Set Subscription.content to one of: 'empty' (notification only), 'id-only' (notification with resource ids), or 'full-resource' (notification with full resource payload); choose based on PHI sensitivity and processing needs
Set Subscription.contentType to 'application/fhir+json' or 'application/fhir+xml' to specify the MIME type of the notification Bundle payload sent to the webhook
Apply Subscription.filterBy to narrow notifications to a specific patient or resource criteria (e.g., filterBy[0].filterParameter='patient', filterBy[0].value='Patient/123') if the SubscriptionTopic supports patient-scoped filtering
Handle incoming SubscriptionStatus notification Bundles at the webhook endpoint: parse Bundle.entry[0].resource (a SubscriptionStatus) to confirm the subscription id, event count, and then retrieve any referenced resources if content is 'id-only'
Known gotchas
SubscriptionTopic is a new R5 resource — it does not exist in R4 natively; for R4 servers, use the subscriptions-backport IG (hl7.fhir.uv.subscriptions-backport) which backports topic-based Subscriptions using Basic resources and extensions rather than native SubscriptionTopic
The notification payload is a Bundle of type 'subscription-notification' containing a SubscriptionStatus as the first entry — do not assume the payload is a raw resource matching the trigger; parse SubscriptionStatus first
Subscription.endpoint must use HTTPS (not HTTP) in production environments; the server must be able to verify the endpoint is reachable before activating the Subscription (via a handshake ping)
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