Respuesta corta: una Subscription le indica a un servidor FHIR notificar a este endpoint cuando los recursos que coinciden con estas condiciones cambien. En FHIR R4, las condiciones son una cadena de búsqueda (criteria: "Observation?patient=123&code=85354-9") y el servidor envía el recurso coincidente a un REST hook, un websocket, un correo electrónico o un mensaje FHIR. En R4B y R5, el modelo se reconstruyó en torno a SubscriptionTopic: el servidor publica los eventos sobre los que puede notificar, el cliente se suscribe a un tema con filtros, y las notificaciones llegan como un Bundle de tipo subscription-notification que siempre comienza con un recurso SubscriptionStatus. La guía de implementación Subscriptions R5 Backport permite que los servidores R4 ofrezcan el nuevo modelo.
R4: suscripciones basadas en criterios
En FHIR R4, una Suscripción se basa en criterios: el cliente crea un recurso de Suscripción cuyos criterios son una cadena de búsqueda como Observation?code=…&patient=… y cuyo canal es rest-hook, websocket, email, sms o message. El servidor evalúa los criterios contra cada creación y actualización y envía cada recurso coincidente, o una notificación vacía, al 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>"]
}
}
El servidor evalúa los criterios en cada creación y actualización. Cuando un recurso coincide, lo POSTea al endpoint (o POSTea un cuerpo vacío si se omite payload, para que el cliente obtenga el recurso por sí mismo). Funcionó, pero con tres problemas: los servidores no podían indicar qué criterios soportaban, los clientes no podían distinguir una notificación perdida de un período de inactividad, y "un recurso coincidió con una búsqueda" no es lo mismo que "sucedió un evento" (el final de un Encounter no se puede expresar como una búsqueda).
R4B y R5: suscripciones basadas en temas
En FHIR R4B y R5, las suscripciones se basan en temas. El servidor publica recursos de SubscriptionTopic que describen eventos (el recurso, un disparador como create, update, delete o una condición FHIRPath, y filtros permitidos). Un suscriptor crea una Suscripción apuntando a un tema con valores filterBy, un tipo de canal, un endpoint, un período de latido y una configuración de contenido de empty, id-only o full-resource.
SubscriptionTopic es un recurso que publica el servidor, describiendo un evento: qué recurso, qué disparador (creación, actualización, eliminación o una condición FHIRPath como %previous.status != 'finished' and %current.status = 'finished'), y qué filtros puede usar un suscriptor. El suscriptor luego crea una Subscription que apunta al tema:
{
"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 elige cuánto viaja: empty (solo el evento), id-only (referencias, obtén el resto con tu propia autorización), o full-resource. heartbeatPeriod hace que el servidor envíe un latido para que el silencio sea detectable.
Cómo se ve una notificación
Una notificación de suscripción FHIR es un Bundle de tipo subscription-notification cuya primera entrada es un recurso SubscriptionStatus que proporciona la suscripción, el tema, el tipo de notificación (handshake, heartbeat, event-notification, query-status o query-event) y un contador eventsSinceSubscriptionStart para detectar eventos perdidos. Las entradas adicionales transportan los recursos modificados o sus referencias, dependiendo de la configuración de contenido.
Cada notificación es un Bundle de tipo subscription-notification. Su primera entrada es un SubscriptionStatus con la referencia de la suscripción, el tema, el tipo de notificación (handshake, heartbeat, event-notification, query-status, query-event) y un contador eventsSinceSubscriptionStart; una brecha en el contador significa un evento perdido, y el cliente puede llamar a $events para recuperarlo. Las entradas posteriores transportan los recursos o sus referencias, dependiendo de content.
Canales: rest-hook (el servidor POSTea a tu endpoint HTTPS), websocket (el cliente se conecta y recibe notificaciones en el socket, útil para aplicaciones de navegador), email (solo notificación, no datos), message (un Bundle de mensajería FHIR). El canal R4 sms fue eliminado.
Ejecución en producción
Ejecutar Suscripciones FHIR en producción requiere un manejo idempotente con clave en el número de evento y la versión del recurso, seguridad del endpoint que verifique al remitente y nunca trate la carga útil como autorización, tolerancia a bundles agrupados con muchos eventos, una respuesta 2xx a la notificación de handshake inicial y la conciencia de que muchos servidores todavía limitan las suscripciones a servicios backend en lugar de aplicaciones de pacientes.
- Idempotencia. Las notificaciones pueden duplicarse después de un reintento; clave en el número de evento y la versión del recurso.
- Seguridad. El endpoint debe verificar al remitente (un encabezado de secreto compartido, TLS mutuo o firmas) y nunca debe confiar en el payload como autorización; obtén datos sensibles del servidor con tu propio token cuando
contentseaid-only. - Contrapresión. Los servidores agrupan eventos y respetan
maxCount; los clientes deben aceptar bundles con muchos eventos. - Handshake. Al activarse, el servidor envía una notificación
handshakey espera un 2xx; de lo contrario, la suscripción pasa aerror. - Alcances. SMART on FHIR añadió alcances de suscripción lentamente; muchos servidores todavía restringen las suscripciones a servicios backend (credenciales de cliente) en lugar de aplicaciones de pacientes.
Webhooks que no son Suscripciones FHIR
Los webhooks que no son Suscripciones FHIR son mecanismos de plataforma sencillos: registras una URL HTTPS y recibes eventos JSON firmados como resource written o consent changed, sin ningún SubscriptionTopic. Anpheros ofrece dichos webhooks. Son más sencillos para una plataforma, pero no son descubribles por un cliente FHIR genérico, por lo que las integraciones que deben funcionar contra cualquier servidor FHIR utilizan Suscripciones.
Muchas plataformas, incluida Anpheros, ofrecen webhooks simples: registras una URL HTTPS y recibes eventos JSON firmados como recurso escrito, consentimiento cambiado, documento finalizado. Resuelven la misma necesidad con menos ceremonia y sin SubscriptionTopic, y no son recursos FHIR, por lo que un cliente FHIR genérico no puede descubrirlos. Si tu integración debe funcionar contra cualquier servidor FHIR, usa Suscripciones; si se dirige a una plataforma específica, sus webhooks suelen ser más sencillos. Anpheros documenta sus webhooks en el sitio para desarrolladores (enlace abajo).
Páginas relacionadas
- FHIR R4 vs R5
- Búsqueda FHIR explicada
- FHIR Bundle explicado
- CDS Hooks explicado
- Monitorización remota de pacientes con FHIR
- Webhooks de Anpheros (desarrolladores)
Fuentes
- HL7 FHIR R5: Subscription
- HL7 FHIR R5: SubscriptionTopic
- HL7 FHIR R5: SubscriptionStatus and notifications
- HL7 FHIR R4: Subscription
- Guía de implementación Subscriptions R5 Backport
Preguntas frecuentes
¿Puedo usar suscripciones estilo R5 en un servidor R4?
Sí, si el servidor implementa la guía de implementación Subscriptions R5 Backport, que codifica el tema, los filtros y la configuración del canal como extensiones en el recurso R4 Subscription y utiliza Bundles R4 para las notificaciones.
¿Cuál es la diferencia entre una Suscripción y el sondeo con _lastUpdated?
El sondeo pregunta al servidor repetidamente y no se pierde nada, pero es lento y derrochador; las Suscripciones envían eventos a medida que ocurren. Los clientes robustos combinan ambos: suscríbete para velocidad, sondea o llama a $events para recuperarte después de una interrupción.
¿La notificación contiene los datos?
Solo si content es full-resource. El valor predeterminado más seguro es id-only: la notificación te dice qué recurso cambió y tú lo obtienes con tu propia autorización.
¿Son las Suscripciones FHIR lo mismo que los webhooks?
Una suscripción rest-hook es un webhook con una forma definida por FHIR: temas descubribles, bundles de notificación estándar y seguimiento de estado. Los webhooks simples ofrecidos por una plataforma hacen el mismo trabajo solo para esa plataforma.
Pruébalo gratis en el sandbox
Tu primera llamada FHIR en 5 minutos. Una API HL7 FHIR R4 con el consentimiento del paciente integrado: pruébala en el sandbox y luego conecta tu propia app o sistema de clínica.
Gratis · 30 pacientes sintéticos · sin tarjeta
Anpheros crea un historial médico que el paciente controla y puede compartir con cualquier clínica, en una plataforma HL7 FHIR R4, con sede en la UE. Estas guías te ayudan a entender y organizar tu salud; no reemplazan a tu médico.
Sobre Anpheros →