Subscrições FHIR explicadas: tópicos, canais, R4 a R5

Q: A notificação contém os dados?

Apenas se content for full-resource . O padrão mais seguro é id-only : a notificação diz-lhe qual recurso mudou, e você obtém-no com a sua própria autorização.

Resposta curta: Uma Subscription diz a um servidor FHIR para notificar este endpoint quando recursos que correspondem a estas condições mudarem. Em FHIR R4, as condições são uma string de pesquisa (criteria: "Observation?patient=123&code=85354-9") e o servidor envia o recurso correspondente para um REST hook, um websocket, um email ou uma mensagem FHIR. Em R4B e R5, o modelo foi reconstruído em torno de SubscriptionTopic: o servidor publica os eventos sobre os quais pode notificar, o cliente subscreve um tópico com filtros, e as notificações chegam como um Bundle do tipo subscription-notification que começa sempre com um recurso SubscriptionStatus. O guia de implementação Subscriptions R5 Backport permite que servidores R4 ofereçam o novo modelo.

R4: Subscrições baseadas em critérios

Em FHIR R4, uma Subscrição é baseada em critérios: o cliente cria um recurso de Subscrição cujos critérios são uma string de pesquisa como Observation?code=…&patient=… e cujo canal é rest-hook, websocket, email, sms ou message. O servidor avalia os critérios em cada criação e atualização e envia cada recurso correspondente, ou uma notificação vazia, para o 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>"]
  }
}

O servidor avalia os critérios em cada criação e atualização. Quando um recurso corresponde, envia-o para o endpoint (ou envia um corpo vazio se payload for omitido, para que o cliente obtenha o recurso ele próprio). Funcionou, mas com três problemas: os servidores não conseguiam dizer quais critérios suportavam, os clientes não conseguiam distinguir uma notificação perdida de um período de silêncio, e "um recurso correspondeu a uma pesquisa" não é o mesmo que "um evento aconteceu" (o fim de um Encounter não pode ser expresso como uma pesquisa).

R4B e R5: Subscrições baseadas em tópicos

Em FHIR R4B e R5, as subscrições são baseadas em tópicos. O servidor publica recursos SubscriptionTopic que descrevem eventos (o recurso, um gatilho como create, update, delete ou uma condição FHIRPath, e filtros permitidos). Um subscritor cria uma Subscrição apontando para um tópico com valores filterBy, um tipo de canal, um endpoint, um período de heartbeat e uma configuração de conteúdo de empty, id-only ou full-resource.

SubscriptionTopic é um recurso que o servidor publica, descrevendo um evento: qual recurso, qual gatilho (criação, atualização, eliminação ou uma condição FHIRPath como %previous.status != 'finished' and %current.status = 'finished'), e quais filtros um subscritor pode usar. O subscritor cria então uma Subscription que aponta para o tópico:

{
  "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 escolhe quanta informação é enviada: empty (apenas o evento), id-only (referências, obtenha o resto com a sua própria autorização), ou full-resource. heartbeatPeriod faz com que o servidor envie um heartbeat para que o silêncio seja detetável.

Como é uma notificação

Uma notificação de subscrição FHIR é um Bundle do tipo subscription-notification cuja primeira entrada é um recurso SubscriptionStatus que fornece a subscrição, o tópico, o tipo de notificação (handshake, heartbeat, event-notification, query-status ou query-event) e um contador eventsSinceSubscriptionStart para detetar eventos em falta. Entradas adicionais transportam os recursos alterados ou as suas referências, dependendo da configuração de conteúdo.

Cada notificação é um Bundle do tipo subscription-notification. A sua primeira entrada é um SubscriptionStatus com a referência da subscrição, o tópico, o tipo de notificação (handshake, heartbeat, event-notification, query-status, query-event) e um contador eventsSinceSubscriptionStart; uma lacuna no contador significa um evento perdido, e o cliente pode chamar $events para o recuperar. Entradas adicionais carregam os recursos ou as suas referências, dependendo de content.

Canais: rest-hook (o servidor POSTa para o seu endpoint HTTPS), websocket (o cliente conecta-se e recebe notificações no socket, útil para aplicações de navegador), email (apenas notificação, sem dados), message (um Bundle de mensagens FHIR). O canal R4 sms foi descontinuado.

Execução em produção

Executar Subscrições FHIR em produção requer tratamento idempotente com chave no número do evento e versão do recurso, segurança do endpoint que verifica o remetente e nunca trata o payload como autorização, tolerância para bundles em lote com muitos eventos, uma resposta 2xx à notificação inicial de handshake e a consciência de que muitos servidores ainda limitam as subscrições a serviços de backend em vez de aplicações de pacientes.

Idempotência. As notificações podem ser duplicadas após uma nova tentativa; use o número do evento e a versão do recurso como chave.
Segurança. O endpoint deve verificar o remetente (um cabeçalho de segredo partilhado, TLS mútuo ou assinaturas) e nunca deve confiar no payload como autorização; obtenha dados sensíveis de volta do servidor com o seu próprio token quando content for id-only.
Backpressure. Os servidores agrupam eventos e respeitam maxCount; os clientes devem aceitar bundles com muitos eventos.
Handshake. Na ativação, o servidor envia uma notificação handshake e espera um 2xx; caso contrário, a subscrição passa para error.
Escopos. SMART on FHIR adicionou escopos de subscrição lentamente; muitos servidores ainda restringem as subscrições a serviços de backend (credenciais de cliente) em vez de aplicações de pacientes.

Webhooks que não são Subscrições FHIR

Webhooks que não são Subscrições FHIR são mecanismos de plataforma simples: regista um URL HTTPS e recebe eventos JSON assinados como resource written ou consent changed, sem qualquer SubscriptionTopic. A Anpheros oferece tais webhooks. São mais simples para uma plataforma, mas não são descobertos por um cliente FHIR genérico, pelo que as integrações que devem funcionar contra qualquer servidor FHIR utilizam Subscrições.

Muitas plataformas, incluindo Anpheros, oferecem webhooks simples: regista um URL HTTPS e recebe eventos JSON assinados como recurso escrito, consentimento alterado, documento finalizado. Eles resolvem a mesma necessidade com menos cerimónia e sem SubscriptionTopic, e não são recursos FHIR, pelo que um cliente FHIR genérico não os pode descobrir. Se a sua integração tem de funcionar contra qualquer servidor FHIR, use Subscrições; se tem como alvo uma plataforma, os seus webhooks são geralmente mais simples. Anpheros documenta os seus webhooks no site para programadores (link abaixo).

Páginas relacionadas

Fontes

Perguntas frequentes

Posso usar subscrições no estilo R5 num servidor R4?

Sim, se o servidor implementar o guia de implementação Subscriptions R5 Backport, que codifica o tópico, filtros e configurações de canal como extensões no recurso R4 Subscription e usa Bundles R4 para notificações.

Qual é a diferença entre uma Subscription e polling com _lastUpdated?

O polling pergunta ao servidor repetidamente e não perde nada, mas é lento e desperdiçador; as Subscrições enviam eventos à medida que acontecem. Clientes robustos combinam ambos: subscrevem para velocidade, fazem polling ou chamam $events para recuperar após inatividade.

A notificação contém os dados?

Apenas se content for full-resource. O padrão mais seguro é id-only: a notificação diz-lhe qual recurso mudou, e você obtém-no com a sua própria autorização.

As Subscrições FHIR são o mesmo que webhooks?

Uma subscrição rest-hook é um webhook com uma forma definida pelo FHIR: tópicos descobríveis, bundles de notificação padrão e acompanhamento de estado. Webhooks simples oferecidos por uma plataforma fazem o mesmo trabalho apenas para essa plataforma.

Anpheros Platform

Experimente grátis no sandbox

Sua primeira chamada FHIR em 5 minutos. Uma API HL7 FHIR R4 com o consentimento do paciente integrado: experimente na sandbox e depois conecte a sua própria app ou sistema clínico.

Criar um sandbox grátis Ler os guias para programadores →

Grátis · 30 pacientes sintéticos · sem cartão

Este guia é meramente informativo e não substitui aconselhamento médico. Para decisões sobre a sua saúde, fale com o seu médico. Em uma emergência, ligue para o número de emergência local (112 na Europa).

Escrito por

A equipa Anpheros

A Anpheros desenvolve um registo médico que o doente controla e pode partilhar com qualquer clínica, numa plataforma HL7 FHIR R4, sediada na UE. Estes guias ajudam-no a compreender e organizar a sua saúde; não substituem o seu médico.

Sobre a Anpheros →