FHIR Subscriptions: Building Real-Time Event-Driven Healthcare Apps

The Polling Problem

// Poll every 30 seconds
while (true)
{
    var newResults = await fhirClient.SearchAsync<Observation>(
        new SearchParams()
            .Where("patient=Patient/12345")
            .Where("category=laboratory")
            .Where($"date=gt{lastCheck}")
    );
    
    ProcessResults(newResults);
    await Task.Delay(30000); // 30 seconds
}

// One-time setup
var subscription = new Subscription
{
    Criteria = "Observation?category=laboratory",
    Channel = new Subscription.ChannelComponent
    {
        Type = Subscription.SubscriptionChannelType.RestHook,
        Endpoint = "https://myapp.ie/fhir/webhook"
    }
};

await fhirClient.CreateAsync(subscription);

// Server pushes to webhook when new lab result created
// No polling needed!

Understanding FHIR Subscriptions

FHIR R4 vs R5 Subscriptions

FHIR Subscription Architecture

FHIR R4 Subscription Implementation

Creating an R4 Subscription

{
  "resourceType": "Subscription",
  "id": "patient-admit-subscription",
  "status": "requested",
  "reason": "Monitor patient admissions for real-time alerts",
  "criteria": "Encounter?status=in-progress&class=inpatient",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://myapp.healthcare.com/fhir/webhook",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer ${AUTH_TOKEN}",
      "X-Subscription-Id: patient-admit-subscription"
    ]
  },
  "end": "2025-12-31T23:59:59Z"
}

.NET FHIR Subscription Client

using Hl7.Fhir.Model;
using Hl7.Fhir.Rest;

public class FhirSubscriptionService
{
    private readonly FhirClient _client;
    private readonly ILogger<FhirSubscriptionService> _logger;

    public FhirSubscriptionService(string fhirServerUrl, ILogger<FhirSubscriptionService> logger)
    {
        _client = new FhirClient(fhirServerUrl);
        _logger = logger;
    }

    public async Task<Subscription> CreatePatientAdmitSubscriptionAsync(string webhookUrl)
    {
        var subscription = new Subscription
        {
            Status = Subscription.SubscriptionStatus.Requested,
            Reason = "Monitor patient admissions",
            Criteria = "Encounter?status=in-progress&class=inpatient",
            Channel = new Subscription.ChannelComponent
            {
                Type = Subscription.SubscriptionChannelType.RestHook,
                Endpoint = webhookUrl,
                Payload = "application/fhir+json",
                Header = new List<string>
                {
                    $"Authorization: Bearer {GetAuthToken()}",
                    "Content-Type: application/fhir+json"
                }
            },
            End = DateTimeOffset.UtcNow.AddYears(1).ToString("o")
        };

        var created = await _client.CreateAsync(subscription);
        _logger.LogInformation("Subscription created: {Id}", created.Id);
        return created;
    }

    public async Task<bool> DeleteSubscriptionAsync(string subscriptionId)
    {
        try
        {
            await _client.DeleteAsync($"Subscription/{subscriptionId}");
            return true;
        }
        catch (FhirOperationException ex)
        {
            _logger.LogError(ex, "Failed to delete subscription {Id}", subscriptionId);
            return false;
        }
    }
}

ASP.NET Core Webhook Handler

[ApiController]
[Route("fhir/webhook")]
public class FhirWebhookController : ControllerBase
{
    private readonly ILogger<FhirWebhookController> _logger;
    private readonly IEventProcessor _eventProcessor;
    private readonly FhirJsonParser _parser = new();

    public FhirWebhookController(
        ILogger<FhirWebhookController> logger,
        IEventProcessor eventProcessor)
    {
        _logger = logger;
        _eventProcessor = eventProcessor;
    }

    [HttpPost]
    public async Task<IActionResult> HandleNotification()
    {
        using var reader = new StreamReader(Request.Body);
        var body = await reader.ReadToEndAsync();

        // Handle handshake (empty body)
        if (string.IsNullOrWhiteSpace(body))
        {
            _logger.LogInformation("Subscription handshake received");
            return Ok();
        }

        try
        {
            var bundle = _parser.Parse<Bundle>(body);
            
            foreach (var entry in bundle.Entry)
            {
                if (entry.Resource is Encounter encounter)
                {
                    await ProcessEncounterEventAsync(encounter);
                }
                else if (entry.Resource is Patient patient)
                {
                    await ProcessPatientEventAsync(patient);
                }
            }

            return Ok();
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to process FHIR notification");
            return StatusCode(500);
        }
    }

    private async Task ProcessEncounterEventAsync(Encounter encounter)
    {
        _logger.LogInformation(
            "Encounter event: {Id}, Status: {Status}, Class: {Class}",
            encounter.Id,
            encounter.Status,
            encounter.Class?.Code);

        await _eventProcessor.PublishAsync(new PatientAdmitEvent
        {
            EncounterId = encounter.Id,
            PatientReference = encounter.Subject?.Reference,
            AdmitTime = DateTimeOffset.UtcNow
        });
    }
}

FHIR R5 Topic-Based Subscriptions

SubscriptionTopic Definition

{
  "resourceType": "SubscriptionTopic",
  "id": "patient-admission",
  "url": "http://example.org/fhir/SubscriptionTopic/patient-admission",
  "title": "Patient Admission Events",
  "status": "active",
  "description": "Notification when a patient is admitted",
  "resourceTrigger": [
    {
      "description": "Trigger on Encounter creation or update to in-progress",
      "resource": "Encounter",
      "supportedInteraction": ["create", "update"],
      "queryCriteria": {
        "previous": "status:not=in-progress",
        "resultForCreate": "test-passes",
        "current": "status=in-progress&class=inpatient",
        "resultForDelete": "test-fails",
        "requireBoth": true
      }
    }
  ],
  "canFilterBy": [
    {
      "description": "Filter by patient",
      "resource": "Encounter",
      "filterParameter": "patient"
    },
    {
      "description": "Filter by location",
      "resource": "Encounter",
      "filterParameter": "location"
    }
  ],
  "notificationShape": [
    {
      "resource": "Encounter",
      "include": ["Encounter:patient", "Encounter:location"]
    }
  ]
}

R5 Subscription with Filters

{
  "resourceType": "Subscription",
  "id": "icu-admissions",
  "status": "requested",
  "topic": "http://example.org/fhir/SubscriptionTopic/patient-admission",
  "reason": "Monitor ICU admissions only",
  "filterBy": [
    {
      "filterParameter": "location",
      "value": "Location/icu-ward"
    }
  ],
  "channelType": {
    "system": "http://terminology.hl7.org/CodeSystem/subscription-channel-type",
    "code": "rest-hook"
  },
  "endpoint": "https://alerts.hospital.com/fhir/icu-webhook",
  "contentType": "application/fhir+json",
  "content": "full-resource",
  "maxCount": 10
}

Common Subscription Patterns

Production Architecture with Azure

graph TB
    subgraph "FHIR Server"
        FS[Azure API for FHIR]
    end
    
    subgraph "Event Processing"
        EG[Event Grid]
        SB[Service Bus]
        AF[Azure Functions]
    end
    
    subgraph "Applications"
        WA[Clinical Dashboard]
        MA[Mobile Alert App]
        AN[Analytics Pipeline]
    end
    
    FS --> EG
    EG --> SB
    SB --> AF
    AF --> WA
    AF --> MA
    AF --> AN
    
    style FS fill:#E3F2FD,stroke:#2196F3
    style EG fill:#E8F5E9,stroke:#4CAF50
    style SB fill:#FFF3E0,stroke:#FF9800
    style AF fill:#F3E5F5,stroke:#9C27B0

Subscription Channel Types

{
  "resourceType": "Subscription",
  "status": "active",
  "criteria": "Observation?code=http://loinc.org|2339-0",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://myapp.ie/fhir/notifications",
    "payload": "application/fhir+json",
    "header": [
      "Authorization: Bearer eyJhbGc..."
    ]
  }
}

{
  "channel": {
    "type": "websocket",
    "endpoint": "wss://fhir.server/ws/subscription/123"
  }
}

{
  "channel": {
    "type": "message",
    "endpoint": "Endpoint=sb://myfhir.servicebus.windows.net/;...",
    "payload": "application/fhir+json"
  }
}

{
  "channel": {
    "type": "email",
    "endpoint": "mailto:oncall@hospital.ie",
    "payload": "text/plain"
  }
}

Hospital Use Cases

var subscription = new Subscription
{
    Status = Subscription.SubscriptionStatus.Active,
    Criteria = "Observation?code=http://loinc.org|10839-9&value=gt0.04",
    Channel = new Subscription.ChannelComponent
    {
        Type = Subscription.SubscriptionChannelType.RestHook,
        Endpoint = "https://icu-dashboard.hospital.ie/alerts/cardiac"
    }
};

var subscription = new Subscription
{
    Criteria = "Encounter?class=IMP&location=Location/OR-5",
    Channel = new Subscription.ChannelComponent
    {
        Type = Subscription.SubscriptionChannelType.WebSocket,
        Endpoint = "wss://or-board.hospital.ie/ws"
    }
};

var subscription = new Subscription
{
    Criteria = "MedicationRequest?status=active&priority=urgent",
    Channel = new Subscription.ChannelComponent
    {
        Type = Subscription.SubscriptionChannelType.Message,
        Endpoint = "Endpoint=sb://hospital.servicebus.windows.net/;..."
    }
};

Why FHIR Subscriptions Matter in Healthcare

Advantages of FHIR Subscriptions

Challenges and Limitations

Adoption Roadmap

graph LR
    %% Global Styles
    classDef phase fill:#f9f9f9,stroke:#333,stroke-width:2px;
    classDef p1 fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1;
    classDef p2 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20;
    classDef p3 fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,color:#e65100;
    classDef p4 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c;

    %% Added 
 breaks to the title below to push the boxes down
    subgraph Roadmap [FHIR Subscriptions Implementation Path




]
    
        direction LR
        
        P1(Phase 1: Assessment & Planning
4-6 Weeks

• Vendor Capability Check
• Use Case Prioritization
• Security Review InfoSec
• Infra Planning Webhooks/Queues
• HIPAA Compliance Mapping):::p1
        
        P2(Phase 2: Pilot Implementation
6-8 Weeks

• Non-Prod Dev Setup
• Single Use Case e.g., Lab Results
• End-to-End Testing
• Failure Mode Testing Retry/Dead-letter
• Establish Performance Baseline):::p2
        
        P3(Phase 3: Production Rollout
4-6 Weeks

• Security Hardening mTLS/Signatures
• Observability Logs/Metrics
• Gradual Rollout Subset of users
• Runbook Creation
• Ops Team Training):::p3
        
        P4(Phase 4: Scale & Optimize
Ongoing

• Expand Use Cases
• Tuning Batch sizes/Parallelism
• R5 Topic-Based Migration
• Self-Service Portal Implementation):::p4
    end

    %% Connections
    P1 --> P2
    P2 --> P3
    P3 --> P4

Governance and Operational Excellence

Subscription Governance Framework

Maintenance and Monitoring

Key Metrics to Track

Key Takeaways

• ✅ FHIR Subscriptions enable real-time healthcare – Move from polling to push-based architecture
• ✅ R5 Topic-Based is the future – Better governance, richer filtering, backport available
• ✅ Secure your webhooks – HTTPS, authentication, signature verification
• ✅ Design for failure – Retries, idempotency, dead-letter queues
• ✅ Start with specific criteria – Avoid notification storms from overly broad subscriptions
• ✅ Monitor subscription health – Track delivery rates and latency

Conclusion

Standards and References

Related Articles in This Series

Conclusion