Implement FHIR R5 topic-based Subscriptions using SubscriptionTopic and Subscription with a rest-hook channel

In-depth guide

Steps

1. 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
2. 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
3. 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
4. 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
5. 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
6. 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'