CDS Hooks Explained: Real-Time Clinical Decision Support with FHIR
SMART on FHIR lets you launch an app inside the EHR. But what if you want to surface a real-time alert the moment a clinician places an order, without them opening anything? That's CDS Hooks: a clinical decision support FHIR standard that fires automatically inside the clinician's workflow. It brings relevant insights directly to the point of care, reducing friction and keeping the clinician focused on the patient rather than hunting for information.
What CDS Hooks Are
This specification is designed to trigger external decision support during EHR workflow events. Unlike SMART apps that require a clinician to launch them, the standard operates in the background with no launch and no UI to open. The EHR calls your service at specific moments, and your service responds with guidance. The specification describes a hook-based pattern for invoking decision support, with the API supporting synchronous, workflow-triggered calls that return information and suggestions. It is a lightweight, RESTful approach using JSON over HTTPS to integrate clinical decision support between EHRs and external services.
SMART Apps vs CDS Hooks
When deciding which to use, consider the user experience. If the clinician needs to make a decision and the information can be presented in a card, use CDS Hooks. If they need to complete a more involved process, a SMART app is the better fit.
The Hook and Card Model
Hooks are the events that trigger your service. Common hooks include patient-view when a patient chart is opened, order-select when a clinician is choosing orders, and order-sign right before an order is finalized. Each hook provides context: for patient-view, the EHR sends the patient ID; for order-select, it sends the draft orders being considered.
Cards are what your service returns. There are three types: information cards that display text for the clinician to read, suggestion cards that provide actionable recommendations with buttons the clinician can click to accept, and app link cards that launch a SMART app or external resource. The flow is straightforward: the EHR fires a hook, your service evaluates the context and any prefetched data, and returns cards. The EHR then displays those cards directly in the clinician's workflow. Cards can include FHIR-formatted data and link to external knowledge resources.
Real Use Cases
Drug-drug interaction alerts are a classic example. When a clinician prescribes a new medication, the order-select hook fires, your service checks the patient's active medication list against the new order, and returns a warning card if an interaction is found. Duplicate order detection works similarly: a suggestion card can alert the clinician that an identical lab test was ordered recently, potentially saving time and reducing waste.
Clinical guideline prompts can be triggered on patient-view. For example, a service that identifies patients with a specific diagnosis and suggests screening or treatment options based on current guidelines. Cost-of-care transparency is another growing use case: when an order is selected, your service could return a card showing the estimated cost to the patient and suggest lower-cost alternatives.
We recently built decision support for a multi-tenant clinical platform serving oncology and emergency departments. The challenge was handling diverse workflows: oncology needed protocol adherence checks for complex chemotherapy regimens, while the ER needed rapid alerts for critical lab values and sepsis screening. Using a hook-based architecture, we built a single service that could evaluate both contexts. For the oncology workflow, we listened for order-select and checked the proposed regimen against the patient's genomic profile and clinical guidelines. For the ER, we used patient-view to trigger a sepsis risk assessment. The response time was critical: clinicians don't wait, so we optimized our evaluation logic to return cards in under 200 milliseconds.
Implementation Considerations
Latency matters. Clinicians won't wait for a slow service. The specification recommends responding on the order of 500 milliseconds. Use prefetch to have the EHR send the data your service needs rather than making additional FHIR calls after the hook fires. This reduces round trips and speeds up response times.
Alert fatigue is real. Only fire when genuinely useful. Over-alerting leads to clinicians ignoring your cards, or worse, disabling your service entirely. Use usage requirements to communicate preconditions for your service. Test in a sandbox before production. The CDS Hooks community provides a sandbox at http://sandbox.cds-hooks.org for testing your service without affecting live EHRs.
Auth and PHI handling are critical. The hook payload may contain protected health information, so ensure your service is HIPAA-compliant and uses appropriate authentication. The specification supports OAuth 2.0 bearer tokens for FHIR resource access, and the fhirAuthorization field can be used to pass authorization information to your service.
FAQs
What's the difference between SMART on FHIR and CDS Hooks?
SMART on FHIR requires a clinician to launch an app. CDS Hooks fires automatically in the background at specific workflow moments, like placing an order, and returns a card with no launch required. They're complementary: a CDS Hooks card can link to a SMART app when deeper interaction is needed.
What are the three types of CDS Hooks cards?
Information cards display text for the clinician to read, suggestion cards provide actionable recommendations with clickable buttons, and app link cards launch a SMART app or external resource. The EHR displays whichever card type your service returns directly in the clinician's workflow.
What are common CDS Hooks triggers?
patient-view fires when a chart is opened, order-select fires while a clinician is choosing orders, and order-sign fires right before an order is finalized. Each hook sends relevant context, such as the patient ID for patient-view or the draft orders being considered for order-select.
How fast does a CDS Hooks service need to respond?
The specification recommends responding on the order of 500 milliseconds, since clinicians won't wait for a slow service. In one multi-tenant clinical platform project, cards were returned in under 200 milliseconds for both oncology and emergency department workflows.
What's a real example of CDS Hooks in use?
Drug-drug interaction alerts: when a clinician prescribes a medication, the order-select hook fires, the service checks it against the patient's active medication list, and returns a warning card if an interaction is found, all without the clinician opening anything extra.
How should PHI be handled in a CDS Hooks service?
The hook payload may contain protected health information, so the service needs to be HIPAA-compliant with appropriate authentication. The specification supports OAuth 2.0 bearer tokens, and a fhirAuthorization field can pass authorization details to your service.
Conclusion
CDS Hooks bring decision support into the workflow, not beside it. By firing automatically at the right moments and returning concise, actionable cards, they help clinicians make better decisions without disrupting their flow. Start simple: build a service that responds to one hook with a single card, test it in the sandbox, and iterate from there.
For a deeper dive, explore SMART on FHIR to understand how app link cards work, and read What Is FHIR to understand the data layer beneath it all. If you are handling sensitive data, our guide to Building HIPAA-Compliant APIs is essential reading. If you're looking for a practical CDS Hooks tutorial, start by implementing a single hook, returning one card, and testing the workflow in a sandbox environment before moving to production.
