CDS Hooks Explained: Adding Decision Support Inside the EHR

In a 2021 review of four clinical decision-support standards, only 5 of 44 included studies described systems deployed in real-world settings; CDS Hooks appeared in 8 of the 44. That early evidence base is a useful reminder that standards conformance alone doesn't prove an integration will work in a specific EHR or improve clinical outcomes. The peer-reviewed review gives product teams a reason to validate workflow fit, data quality, and clinical performance alongside protocol behavior.

CDS Hooks gives an EHR a standard way to call an external decision-support service at a defined workflow point and display its response. The engineering challenge is making that exchange useful and safe across EHRs whose supported hooks, data, and actions can differ. This guide covers the hook and card model, prefetch and SMART app links, vendor support, a hypothetical order-select flow, alert fatigue, and the FDA's current CDS guidance.

What CDS Hooks Is

HL7 released CDS Hooks version 2 in August 2022, and the current v2.0.1 specification is based on FHIR R4. Decision logic needs to run at a defined point in an EHR workflow without being copied into every vendor build. The CDS Hooks specification defines the call pattern: the EHR, acting as the CDS client, invokes an external service when a named hook fires, sends workflow and patient context, and receives a synchronous response.

CDS Hooks grew out of the SMART on FHIR ecosystem, which was introduced to let healthcare applications run across different health IT systems without being rewritten for each vendor. CDS Hooks became an HL7 specification managed by the HL7 Clinical Decision Support Workgroup. Its workflow events can include patient review and ordering, and a service can return information, recommendations, suggested actions, or a link to a SMART app when the user needs a longer interaction. MITRE's overview of SMART on FHIR and CDS Hooks describes this evolution and the separation between the EHR, FHIR data access, and decision-support logic.

For clinical software integration, that separation sets clear engineering boundaries. The EHR owns when the service is called; the external service owns decision logic that can be versioned and tested apart from the chart; FHIR R4 provides the shared data model.

Hooks, Services and Cards

A hook is a named point in an EHR workflow. A service is the external endpoint the EHR calls when that hook fires. A card is a unit of content the service returns for the EHR to display. Cards can provide information, suggest an action, or offer a link to a SMART app; the clinician reviews the content within the EHR.

Hook	Fires when	Context and data sent	Typical use
patient-view	The clinician opens the patient chart	Patient and user context, with optional prefetch	Background risk summaries and care gap reminders
order-select	The clinician selects orders during ordering	Draft orders and patient context, with optional prefetch	Order-time information and suggestions; intended to replace medication-prescribe
order-sign	Orders are ready to be signed	Draft MedicationRequest or ServiceRequest resources, with prefetch	Final checks before the order is committed
medication-prescribe	Medication ordering occurs through this legacy hook	Draft medication context	Older integrations; verify target EHR support before use

These are common examples, not a guaranteed hook set. The specification doesn't require every EHR to implement the same hooks or call them at identical workflow points, so product requirements should name the precise event and payload the target EHR supports.

A response can also contain systemActions, which sit outside cards. The CDS client may apply them automatically without showing a user-facing card. Because these actions can change workflow or write FHIR resources with less direct clinician review, treat them as high-risk capabilities. The HL7 Da Vinci CRD card guidance describes the distinction between cards and system actions.

Constrain system actions to narrow use cases, validate authorization and proposed changes on the server, record audit events, and test idempotency and conflict handling. The client decides whether to apply an action, so test the behavior in each EHR rather than assuming every platform handles it the same way.

Prefetch and SMART App Links

Prefetch lets the EHR attach requested FHIR resources to the initial hook request. With order-select, for example, the request can already include the patient, user, draft order, and requested recent Observation resources. That can spare the service a series of extra FHIR reads and make response timing more predictable for a synchronous clinician-facing exchange. The CDS Hooks implementation specification describes the RESTful, JSON-based request and the use of prefetch.

If the prefetched data isn't enough, the request may include a FHIR server endpoint and authorization context. The service then needs to use a valid bearer access token when calling that server. More network calls can add latency and introduce failures, so keep prefetch templates narrow, payloads small, and token scopes checked.

Ownership should be explicit:

1. The EHR determines which prefetch templates it honors and which scopes it issues.

2. The CDS service defines its template needs, limits payload size, and validates tokens and scopes.

3. The product team defines what happens if a required resource is missing and ensures the same policy is used across clients.

A card can link to a SMART app when the task needs a form or a longer session than a card can support. The app can handle deeper interaction while the hook response stays focused on the immediate workflow. For the distinction between hook-based launch and app-level interaction, see SMART on FHIR.

Before production, test the boundary with narrow templates, small payloads, scope validation, and a working path when optional prefetch is omitted. A fast response that lacks a required input still needs a deliberate product decision, not an unqualified recommendation.

EHR Support Across Vendors

Two EHRs can both support CDS Hooks and still differ in which hooks they fire, what data they send, and what actions their clients accept. The specification doesn't prescribe a mandatory hook set, and implementation behavior can change. The current documentation says athenahealth's implementation follows CDS Hooks 2.0, but that fact doesn't establish feature parity with another implementation.

Before design, the product team should own a compatibility matrix for each target EHR and site configuration. Confirm:

• Which hooks fire, at what workflow point, and with what context fields.

• Whether the EHR honors the required prefetch templates and returns the expected FHIR resources.

• Which authorization scopes it issues and how the service can access additional FHIR data.

• Whether the client supports systemActions and whether it may apply them automatically.

• How unsupported hooks, responses, and actions are handled, including the fallback behavior.

The practical gap can affect the intended intervention itself. A 2025 case report in Applied Clinical Informatics found that researchers couldn't use CDS Hooks to suppress vendor-supplied drug-allergy alerts because the commercial EHR implementations supported specific scenarios for creating new alerts, not controlling existing vendor alerts. The CDS Hooks specification documentation reflects the flexibility that makes client-specific verification necessary.

We recommend treating CDS Hooks as an augmentation mechanism for a defined workflow, rather than assuming it can replace an EHR's native decision-support infrastructure. A compatibility test should distinguish between “the EHR can display a recommendation” and “the EHR can modify or suppress native behavior.” Build a fallback for any required hook or action the target client doesn't support.

A Worked Example Flow

Hypothetical example: A clinic wants a service to assess a draft medication order alongside recent lab data. The clinical rule below is illustrative only, not medical advice or a validated recommendation.

1. The clinician selects an order. The EHR fires order-select and prepares the hook request. The event occurs while the clinician is choosing the draft order, so the response can inform that workflow moment.

2. The EHR sends context and prefetch. The request includes patient and user identifiers, the draft order, and a prefetch block requesting recent lab Observation resources. The service should rely only on fields and resources verified for that EHR implementation.

3. The service validates the request and data. It checks the request, reads the prefetched resources, and verifies token scope if it needs to call the FHIR server. It also evaluates whether the required lab data is present and sufficiently current under the product's defined policy.

4. The service handles missing or stale inputs conservatively. If required data is missing or stale, it returns an information card that states the gap rather than a recommendation. That response makes the limitation visible without implying that the service has enough evidence to assess the order.

5. The service returns a suggestion when inputs meet policy. If the required data is present, the service returns a suggestion card with a source link and an option to open a SMART app for structured review. Any clinical logic remains illustrative here and requires appropriate clinical validation before use.

6. The EHR renders the result and records the interaction. The EHR displays the card and captures the clinician's choice according to its implementation. The service logs the request, timing, and outcome for technical monitoring and evaluation.

A product such as a clinic AI assistant may involve several connected components, but the hook response should still make its own limits clear. Keep the synchronous card useful on its own; reserve the app launch for review that needs a more structured interface.

Avoiding Alert Fatigue

A clinician overrides a card without recording a reason, and the product team cannot tell whether the rule was a poor fit or a missed opportunity. Repeated interruptions can also weaken attention to useful alerts. Fast prefetch does not resolve incomplete or stale records, unavailable data, or differences in authorization and query behavior. The CDS Hooks ballot documentation describes the need for near-real-time feedback alongside trade-offs among latency, data completeness, and implementation differences.

Set a quality policy before tuning response time. Identify required and optional prefetch data, show its provenance and timestamps on each card, and suppress or downgrade recommendations when critical inputs are missing. If a decision needs more review than a synchronous card supports, use a SMART app launch.

Control when interruptions appear. Fire at the hook where the decision is made, limit cards per encounter, and prefer an information card over an interruptive suggestion when evidence is weak. If clinicians can suppress a rule, capture a reason so product and clinical owners can distinguish a poor-fit rule from a missed opportunity. For products that pair hook-based cards with ongoing clinician-facing engagement, Ekipa AI's HCP Engagement Co-Pilot supports more personalized engagement through intelligent agents.

Measure card acceptance rate, override rate with reason, timeout rate, and time to card render. Review these measures with clinical and product owners. Investigate slow responses and fast responses generated from incomplete inputs; speed alone does not demonstrate that a card is useful. Downgrade or withhold a recommendation when the service cannot establish that its required data is adequate. The broader design trade-offs for clinical decision support systems also apply to hook-based cards.

Regulatory Notes and Next Steps

The FDA updated its Clinical Decision Support software guidance in January 2026, replacing the September 2022 version. The document is guidance, not a statute, and whether software is a medical device depends on whether it meets all non-device CDS criteria. Review the FDA's Clinical Decision Support software guidance with your regulatory and legal advisors.

Technical conformance also doesn't establish clinical value. A 2021 review screened 290 PubMed-indexed articles on FHIR, SMART, Clinical Quality Language, and CDS Hooks; 44 met its criteria, and CDS Hooks appeared in 8 of those included studies. Across the 44, 24 studies were at the design stage, 15 were pilots, and 5 described real-world deployments. Only 12 reported an evaluation, and just two included randomized study components, according to the peer-reviewed review. These findings describe the evidence base at that time; they don't establish the performance of a current product.

For a build decision, confirm target-EHR hooks and actions before implementation, define behavior when prefetch is incomplete, constrain systemActions, and budget for outcome measurement. Engineering should own interface and failure-mode tests; the customer and clinical stakeholders should define workflow fit and acceptable behavior; compliance should assess applicable regulatory obligations and maintain the evidence supporting that assessment.

Conclusion

CDS Hooks can add decision support at defined EHR workflow points, but its practical value depends on verified client capabilities, safe handling of incomplete data, controlled actions, and measured outcomes. For the wider picture of standards and vendor programs, see our EHR integration and interoperability guide. Book a consultation with Ekipa's HealthTech engineers to discuss your integration requirements.

Frequently asked questions

Who publishes the CDS Hooks standard?

CDS Hooks is an HL7 specification managed by the HL7 Clinical Decision Support Workgroup. The CDS Hooks specification is the primary reference for the protocol.

Which FHIR version does CDS Hooks v2.0.1 use?

CDS Hooks v2.0.1 is based on FHIR R4. Confirm that the target EHR's implementation supports the version and resources your service needs.

Do systemActions appear as a card?

No. systemActions are returned outside cards, and the CDS client may apply them automatically without displaying a user-facing card. Verify support and behavior in each target EHR.

What should a service return when prefetch is empty?

If a required input is missing, return an information response or withhold the recommendation according to the product's data-quality policy. Don't present a suggestion that relies on data the service couldn't verify.

Does the January 2026 FDA guidance determine whether a product is a device?

No. The FDA guidance explains how the agency considers Clinical Decision Support software, but it doesn't determine the status of a particular product. Device status depends on whether the software meets all non-device CDS criteria; consult the FDA guidance and obtain product-specific regulatory advice.