Réponse courte : un Subscription indique à un serveur FHIR d'informer cet endpoint lorsque des ressources correspondant à ces conditions changent. Dans FHIR R4, les conditions sont une chaîne de recherche (criteria: "Observation?patient=123&code=85354-9") et le serveur envoie la ressource correspondante à un hook REST, un websocket, un e-mail ou un message FHIR. Dans R4B et R5, le modèle a été reconstruit autour de SubscriptionTopic : le serveur publie les événements sur lesquels il peut notifier, le client s'abonne à un sujet avec des filtres, et les notifications arrivent sous forme de Bundle de type subscription-notification qui commence toujours par une ressource SubscriptionStatus. Le guide d'implémentation Subscriptions R5 Backport permet aux serveurs R4 d'offrir le nouveau modèle.
R4 : abonnements basés sur des critères
Dans FHIR R4, un abonnement est basé sur des critères : le client crée une ressource Subscription dont le critère est une chaîne de recherche telle que Observation?code=…&patient=… et dont le canal est rest-hook, websocket, email, sms ou message. Le serveur évalue le critère par rapport à chaque création et mise à jour et publie chaque ressource correspondante, ou une notification vide, à l'endpoint.
{
"resourceType": "Subscription",
"status": "requested",
"reason": "Blood pressure alerts for the hypertension clinic",
"criteria": "Observation?code=http://loinc.org|85354-9&patient=Patient/123",
"channel": {
"type": "rest-hook",
"endpoint": "https://clinic.example.org/hooks/bp",
"payload": "application/fhir+json",
"header": ["Authorization: Bearer <token>"]
}
}
Le serveur évalue les critères sur chaque création et mise à jour. Lorsqu'une ressource correspond, il la POSTe à l'endpoint (ou POSTe un corps vide si payload est omis, afin que le client récupère lui-même la ressource). Cela fonctionnait, mais avec trois problèmes : les serveurs ne pouvaient pas indiquer quels critères ils supportaient, les clients ne pouvaient pas distinguer une notification manquée d'une période de calme, et "une ressource correspond à une recherche" n'est pas la même chose qu'"un événement s'est produit" (la fin d'une Encounter n'est pas exprimable comme une recherche).
R4B et R5 : abonnements basés sur des sujets
Dans FHIR R4B et R5, les abonnements sont basés sur des sujets. Le serveur publie des ressources SubscriptionTopic décrivant les événements (la ressource, un déclencheur tel que création, mise à jour, suppression ou une condition FHIRPath, et les filtres autorisés). Un abonné crée une Subscription pointant vers un sujet avec des valeurs filterBy, un type de canal, un endpoint, une période de battement et un paramètre de contenu vide, id-only ou full-resource.
SubscriptionTopic est une ressource publiée par le serveur, décrivant un événement : quelle ressource, quel déclencheur (création, mise à jour, suppression, ou une condition FHIRPath comme %previous.status != 'finished' and %current.status = 'finished'), et quels filtres un abonné peut utiliser. L'abonné crée ensuite un Subscription qui pointe vers le sujet :
{
"resourceType": "Subscription",
"status": "requested",
"topic": "http://example.org/fhir/SubscriptionTopic/encounter-end",
"filterBy": [{"resourceType": "Encounter", "filterParameter": "patient", "value": "Patient/123"}],
"channelType": {"system": "http://terminology.hl7.org/CodeSystem/subscription-channel-type", "code": "rest-hook"},
"endpoint": "https://clinic.example.org/hooks/encounters",
"heartbeatPeriod": 60,
"timeout": 30,
"contentType": "application/fhir+json",
"content": "id-only"
}
content choisit la quantité d'informations transmises : empty (juste l'événement), id-only (références, récupérez le reste avec votre propre autorisation), ou full-resource. heartbeatPeriod permet au serveur d'envoyer un battement de cœur pour que le silence soit détectable.
À quoi ressemble une notification
Une notification d'abonnement FHIR est un Bundle de type subscription-notification dont la première entrée est une ressource SubscriptionStatus donnant l'abonnement, le sujet, le type de notification (handshake, heartbeat, event-notification, query-status ou query-event) et un compteur eventsSinceSubscriptionStart pour détecter les événements manqués. Les entrées supplémentaires transportent les ressources modifiées ou leurs références, en fonction du paramètre de contenu.
Chaque notification est un Bundle de type subscription-notification. Sa première entrée est un SubscriptionStatus avec la référence de l'abonnement, le sujet, le type de notification (handshake, heartbeat, event-notification, query-status, query-event) et un compteur eventsSinceSubscriptionStart ; un écart dans le compteur signifie un événement manqué, et le client peut appeler $events pour le récupérer. Les entrées suivantes transportent les ressources ou leurs références, en fonction de content.
Canaux : rest-hook (le serveur POSTe à votre endpoint HTTPS), websocket (le client se connecte et reçoit les notifications sur le socket, utile pour les applications de navigateur), email (notification uniquement, pas de données), message (un Bundle de messagerie FHIR). Le canal R4 sms a été supprimé.
Exécution en production
L'exécution des abonnements FHIR en production nécessite une gestion idempotente indexée sur le numéro d'événement et la version de la ressource, une sécurité de l'endpoint qui vérifie l'expéditeur et ne traite jamais la charge utile comme une autorisation, une tolérance pour les bundles groupés avec de nombreux événements, une réponse 2xx à la notification handshake initiale, et la conscience que de nombreux serveurs limitent encore les abonnements aux services backend plutôt qu'aux applications patient.
- Idempotence. Les notifications peuvent être dupliquées après une nouvelle tentative ; utilisez le numéro d'événement et la version de la ressource comme clés.
- Sécurité. L'endpoint doit vérifier l'expéditeur (un en-tête de secret partagé, TLS mutuel ou signatures) et ne doit jamais faire confiance au payload comme autorisation ; récupérez les données sensibles du serveur avec votre propre jeton lorsque
contentestid-only. - Backpressure. Les serveurs regroupent les événements et respectent
maxCount; les clients doivent accepter les bundles avec de nombreux événements. - Handshake. Lors de l'activation, le serveur envoie une notification
handshakeet attend un 2xx ; sinon, l'abonnement passe àerror. - Scopes. SMART on FHIR a ajouté les scopes d'abonnement lentement ; de nombreux serveurs limitent encore les abonnements aux services backend (informations d'identification client) plutôt qu'aux applications patient.
Webhooks qui ne sont pas des abonnements FHIR
Les webhooks qui ne sont pas des abonnements FHIR sont des mécanismes de plateforme simples : vous enregistrez une URL HTTPS et recevez des événements JSON signés tels que ressource écrite ou consentement modifié, sans aucun SubscriptionTopic. Anpheros propose de tels webhooks. Ils sont plus simples pour une plateforme mais ne sont pas découvrables par un client FHIR générique, donc les intégrations qui doivent fonctionner avec n'importe quel serveur FHIR utilisent les abonnements.
De nombreuses plateformes, y compris Anpheros, proposent des webhooks simples : vous enregistrez une URL HTTPS et recevez des événements JSON signés tels que ressource écrite, consentement modifié, document finalisé. Ils répondent au même besoin avec moins de formalités et sans SubscriptionTopic, et ce ne sont pas des ressources FHIR, donc un client FHIR générique ne peut pas les découvrir. Si votre intégration doit fonctionner avec n'importe quel serveur FHIR, utilisez les abonnements ; si elle cible une plateforme spécifique, ses webhooks sont généralement plus simples. Anpheros documente ses webhooks sur le site développeur (lien ci-dessous).
Pages connexes
- FHIR R4 vs R5
- Recherche FHIR expliquée
- Bundle FHIR expliqué
- CDS Hooks expliqué
- Surveillance à distance des patients avec FHIR
- Webhooks Anpheros (développeurs)
Sources
- HL7 FHIR R5: Subscription
- HL7 FHIR R5: SubscriptionTopic
- HL7 FHIR R5: SubscriptionStatus and notifications
- HL7 FHIR R4: Subscription
- Subscriptions R5 Backport implementation guide
Questions fréquentes
Puis-je utiliser les abonnements de style R5 sur un serveur R4 ?
Oui, si le serveur implémente le guide d'implémentation Subscriptions R5 Backport, qui encode le sujet, les filtres et les paramètres du canal sous forme d'extensions sur la ressource R4 Subscription et utilise des Bundles R4 pour les notifications.
Quelle est la différence entre un abonnement et le polling avec _lastUpdated ?
Le polling interroge le serveur de manière répétée et ne manque rien, mais il est lent et inefficace ; les abonnements poussent les événements au fur et à mesure qu'ils se produisent. Les clients robustes combinent les deux : abonnez-vous pour la rapidité, effectuez un polling ou appelez $events pour récupérer après une interruption.
La notification contient-elle les données ?
Seulement si content est full-resource. La valeur par défaut la plus sûre est id-only : la notification vous indique quelle ressource a changé, et vous la récupérez avec votre propre autorisation.
Les abonnements FHIR sont-ils identiques aux webhooks ?
Un abonnement rest-hook est un webhook avec une forme définie par FHIR : sujets découvrables, bundles de notification standard et suivi de statut. Les webhooks simples proposés par une plateforme font le même travail pour cette plateforme uniquement.
Essayez gratuitement dans le sandbox
Votre premier appel FHIR en 5 minutes. Une API HL7 FHIR R4 avec le consentement du patient intégré : essayez-la dans le bac à sable, puis connectez votre propre application ou système de clinique.
Gratuit · 30 patients synthétiques · sans carte
Anpheros développe un dossier médical que le patient contrôle et peut partager avec n'importe quelle clinique, sur une plateforme HL7 FHIR R4, basée en UE. Ces guides vous aident à comprendre et organiser votre santé ; ils ne remplacent pas votre médecin.
À propos d'Anpheros →