CDS Hooks

The core mechanism that triggers a CDS service at specific points in a clinician's workflow. Hooks are predefined events, such as patient-view or order-select, that the EHR fires automatically. The EHR sends a request to the CDS service, which returns Cards with actionable guidance. This pattern decouples the decision logic from the EHR interface, enabling a plug-and-play ecosystem of external services.

All contextual data is exchanged using FHIR resources. When a hook fires, the EHR assembles a bundle of relevant resources—such as the Patient, current MedicationRequests, and Observations—and sends them to the CDS service. This eliminates proprietary data formats and ensures semantic interoperability across different EHR systems. The service can also execute its own FHIR queries against the EHR's API for additional data.

CDS services return guidance as structured Cards, not arbitrary HTML or text. Each card has a standardized schema including:

• Summary and detail: Human-readable text for the clinician
• Indicator: Urgency level (info, warning, critical)
• Source: Attribution and evidence links
• Suggestions: Actionable proposals with a FHIR-based suggestion structure that can auto-populate an order form This ensures consistent rendering across different EHRs.

To minimize latency, CDS Hooks supports a prefetch mechanism. The service declares which FHIR resources it needs in its discovery document. The EHR then includes those resources directly in the initial hook request, avoiding a round-trip API call. This is critical for real-time decision support where sub-second response times are required during a busy clinical workflow.

Each CDS service exposes a discovery endpoint at {baseUrl}/cds-services. This RESTful endpoint returns a JSON array describing all available services, the hooks they subscribe to, their prefetch templates, and any configuration options. The EHR reads this manifest to understand how to interact with the service, enabling zero-code integration on the EHR side once the discovery URL is registered.

CDS Hooks mandates SMART on FHIR authorization for secure data access. The EHR issues an OAuth 2.0 access token with each hook call, scoped to the specific patient and encounter. The CDS service uses this token to request additional FHIR resources from the EHR's API. This ensures that the service only accesses data the clinician is authorized to see, maintaining HIPAA compliance.

The foundational data standard that CDS Hooks relies on for its data payloads. FHIR defines a set of 'Resources' representing granular clinical concepts (Patient, Observation, MedicationRequest) exchanged via a RESTful API. In a CDS Hooks context, the EHR assembles a context-specific FHIR bundle and transmits it to the decision support service, ensuring the service has a standardized, computable view of the patient's relevant data at the moment of the hook invocation.

An open platform enabling the creation of applications that run seamlessly across the healthcare system. While CDS Hooks defines the service invocation pattern, SMART on FHIR provides the authorization framework using OAuth 2.0. A CDS Service often acts as a SMART on FHIR client, using the access token passed in the hook context to make authenticated FHIR API calls back to the EHR to retrieve additional data not included in the initial hook payload.

An HL7 authoring standard for expressing clinical knowledge in a human-readable, computable format. CQL defines the logic that powers a decision support rule, while CDS Hooks defines the delivery mechanism for surfacing that logic's output in the clinician's workflow. A CDS Service often evaluates a CQL expression against the FHIR data received in the hook context to generate a guidance card.

A mechanism for a client to receive real-time notifications when specific events occur on a FHIR server. While CDS Hooks is a synchronous request-response pattern triggered by a user action, FHIR Subscription enables an event-driven architecture. A CDS Service might use a subscription to pre-fetch and cache patient data, reducing latency when a subsequent hook is fired, or to trigger asynchronous decision support workflows.

An authorization specification for server-to-server communication without direct user interaction. This is the typical authorization model for a CDS Service that needs to make background API calls. The service authenticates using a signed JSON Web Token (JWT) to obtain an access token, allowing it to query the EHR's FHIR API for data not included in the hook's context, such as a full medication history or prior lab results.

A FHIR resource that tracks the origin, authorship, and transformation history of data. In a CDS Hooks context, the Provenance resource is critical for establishing a chain of custody for the clinical data used to generate a recommendation. A CDS Service can use provenance metadata to verify the source and timeliness of data before applying clinical logic, and can append its own provenance record to document that a specific guidance card was generated.