Risposta breve: una Subscription dice a un server FHIR notifica questo endpoint quando le risorse che corrispondono a queste condizioni cambiano. In FHIR R4 le condizioni sono una stringa di ricerca (criteria: "Observation?patient=123&code=85354-9") e il server invia la risorsa corrispondente a un REST hook, un websocket, un'email o un messaggio FHIR. In R4B e R5 il modello è stato ricostruito attorno a SubscriptionTopic: il server pubblica gli eventi di cui può notificare, il client si iscrive a un topic con filtri e le notifiche arrivano come un Bundle di tipo subscription-notification che inizia sempre con una risorsa SubscriptionStatus. La guida all'implementazione Subscriptions R5 Backport consente ai server R4 di offrire il nuovo modello.
R4: iscrizioni basate su criteri
In FHIR R4, una Subscription è basata su criteri: il client crea una risorsa Subscription i cui criteri sono una stringa di ricerca come Observation?code=…&patient=… e il cui canale è rest-hook, websocket, email, sms o message. Il server valuta i criteri rispetto a ogni creazione e aggiornamento e invia ogni risorsa corrispondente, o una notifica vuota, all'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>"]
}
}
Il server valuta i criteri su ogni creazione e aggiornamento. Quando una risorsa corrisponde, la invia tramite POST all'endpoint (o invia un corpo vuoto se payload è omesso, in modo che il client recuperi la risorsa da solo). Ha funzionato, ma con tre problemi: i server non potevano dire quali criteri supportavano, i client non potevano distinguere una notifica persa da un periodo di quiete, e "una risorsa ha corrisposto a una ricerca" non è la stessa cosa di "è successo un evento" (la fine di un Encounter non è esprimibile come una ricerca).
R4B e R5: iscrizioni basate su topic
In FHIR R4B e R5, le subscription sono basate su topic. Il server pubblica risorse SubscriptionTopic che descrivono eventi (la risorsa, un trigger come create, update, delete o una condizione FHIRPath, e filtri consentiti). Un sottoscrittore crea una Subscription puntando a un topic con valori filterBy, un tipo di canale, un endpoint, un periodo di heartbeat e un'impostazione di contenuto di empty, id-only o full-resource.
SubscriptionTopic è una risorsa che il server pubblica, descrivendo un evento: quale risorsa, quale trigger (creazione, aggiornamento, eliminazione o una condizione FHIRPath come %previous.status != 'finished' and %current.status = 'finished'), e quali filtri un sottoscrittore può utilizzare. Il sottoscrittore crea quindi una Subscription che punta al topic:
{
"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 sceglie quanto viene inviato: empty (solo l'evento), id-only (riferimenti, recupera il resto con la tua autorizzazione) o full-resource. heartbeatPeriod fa inviare al server un heartbeat in modo che il silenzio sia rilevabile.
Come appare una notifica
Una notifica di subscription FHIR è un Bundle di tipo subscription-notification la cui prima entry è una risorsa SubscriptionStatus che fornisce la subscription, il topic, il tipo di notifica (handshake, heartbeat, event-notification, query-status o query-event) e un contatore eventsSinceSubscriptionStart per rilevare eventi persi. Le entry successive trasportano le risorse modificate o i loro riferimenti, a seconda dell'impostazione del contenuto.
Ogni notifica è un Bundle di tipo subscription-notification. La sua prima voce è una SubscriptionStatus con il riferimento alla sottoscrizione, il topic, il tipo di notifica (handshake, heartbeat, event-notification, query-status, query-event) e un contatore eventsSinceSubscriptionStart; un intervallo nel contatore significa un evento perso e il client può chiamare $events per recuperarlo. Le voci successive trasportano le risorse o i loro riferimenti, a seconda di content.
Canali: rest-hook (il server invia tramite POST al tuo endpoint HTTPS), websocket (il client si connette e riceve notifiche sul socket, utile per le app del browser), email (solo notifica, nessun dato), message (un Bundle di messaggistica FHIR). Il canale R4 sms è stato eliminato.
Esecuzione in produzione
L'esecuzione di Subscription FHIR in produzione richiede una gestione idempotente basata sul numero dell'evento e sulla versione della risorsa, sicurezza dell'endpoint che verifica il mittente e non considera mai il payload come autorizzazione, tolleranza per bundle in batch con molti eventi, una risposta 2xx alla notifica di handshake iniziale e la consapevolezza che molti server limitano ancora le subscription ai servizi backend piuttosto che alle app per pazienti.
- Idempotenza. Le notifiche possono essere duplicate dopo un nuovo tentativo; usa come chiave il numero dell'evento e la versione della risorsa.
- Sicurezza. L'endpoint deve verificare il mittente (un header con segreto condiviso, TLS reciproco o firme) e non deve mai fidarsi del payload come autorizzazione; recupera i dati sensibili dal server con il tuo token quando
contentèid-only. - Backpressure. I server raggruppano gli eventi e rispettano
maxCount; i client devono accettare bundle con molti eventi. - Handshake. All'attivazione il server invia una notifica
handshakee si aspetta un 2xx; altrimenti la sottoscrizione passa aerror. - Scope. SMART on FHIR ha aggiunto gli scope di sottoscrizione lentamente; molti server limitano ancora le sottoscrizioni ai servizi backend (credenziali client) piuttosto che alle app per pazienti.
Webhook che non sono Subscription FHIR
I webhook che non sono Subscription FHIR sono semplici meccanismi di piattaforma: registri un URL HTTPS e ricevi eventi JSON firmati come risorsa scritta o consenso modificato, senza alcun SubscriptionTopic. Anpheros offre tali webhook. Sono più semplici per una singola piattaforma ma non sono individuabili da un client FHIR generico, quindi le integrazioni che devono funzionare con qualsiasi server FHIR utilizzano le Subscription.
Molte piattaforme, inclusa Anpheros, offrono webhook semplici: registri un URL HTTPS e ricevi eventi JSON firmati come risorsa scritta, consenso modificato, documento finalizzato. Risolvono la stessa esigenza con meno formalità e senza SubscriptionTopic, e non sono risorse FHIR, quindi un client FHIR generico non può scoprirli. Se la tua integrazione deve funzionare con qualsiasi server FHIR, usa le Subscription; se è mirata a una piattaforma, i suoi webhook sono solitamente più semplici. Anpheros documenta i suoi webhook sul sito per sviluppatori (link sotto).
Pagine correlate
- FHIR R4 vs R5
- Ricerca FHIR spiegata
- FHIR Bundle spiegato
- CDS Hooks spiegato
- Monitoraggio remoto dei pazienti con FHIR
- Webhook Anpheros (sviluppatori)
Fonti
- HL7 FHIR R5: Subscription
- HL7 FHIR R5: SubscriptionTopic
- HL7 FHIR R5: SubscriptionStatus e notifiche
- HL7 FHIR R4: Subscription
- Guida all'implementazione Subscriptions R5 Backport
Domande frequenti
Posso usare le iscrizioni in stile R5 su un server R4?
Sì, se il server implementa la guida all'implementazione Subscriptions R5 Backport, che codifica il topic, i filtri e le impostazioni del canale come estensioni sulla risorsa R4 Subscription e utilizza i Bundle R4 per le notifiche.
Qual è la differenza tra una Subscription e il polling con _lastUpdated?
Il polling chiede ripetutamente al server e non perde nulla, ma è lento e dispendioso; le Subscription inviano gli eventi man mano che si verificano. Client robusti combinano entrambi: iscriviti per la velocità, esegui il polling o chiama $events per recuperare dopo un'interruzione.
La notifica contiene i dati?
Solo se content è full-resource. L'impostazione predefinita più sicura è id-only: la notifica ti dice quale risorsa è cambiata e tu la recuperi con la tua autorizzazione.
Le Subscription FHIR sono le stesse dei webhook?
Una sottoscrizione rest-hook è un webhook con una forma definita da FHIR: topic scopribili, bundle di notifica standard e monitoraggio dello stato. I webhook semplici offerti da una piattaforma svolgono lo stesso lavoro solo per quella piattaforma.
Provalo gratis nella sandbox
La tua prima chiamata FHIR in 5 minuti. Un'API HL7 FHIR R4 con il consenso del paziente integrato: provala nella sandbox, poi collega la tua app o il sistema della tua clinica.
Gratis · 30 pazienti sintetici · senza carta
Anpheros sviluppa una cartella clinica che il paziente controlla e può condividere con qualsiasi studio medico, su una piattaforma HL7 FHIR R4, con sede in UE. Queste guide ti aiutano a comprendere e organizzare la tua salute; non sostituiscono il tuo medico.
Chi siamo →