← All articles

CDS Hooks: What Nobody Tells You Before You Build

At 1Putt Health, CDS Hooks integrations are some of the most technically nuanced work we take on for clients. The spec looks clean on paper. The implementation surface is anything but. This article distills the hard lessons from building production CDS Hooks services — the parts the documentation glosses over and the parts that will burn your timeline if you walk in blind.

What CDS Hooks Actually Is

CDS Hooks is an open standard for triggering clinical decision support services at defined points in a clinical workflow — when a provider opens a patient record, writes a prescription, places an order. Your service receives a FHIR-formatted request describing the in-progress workflow, and you return cards: structured UI elements the EHR renders inline for the clinician.

The promise: your logic appears exactly when the provider needs it, surfaced directly inside the EHR without requiring them to leave the workflow.

The gap between that promise and production is what this article is about.

1. CDS Hooks Are Not SMART Apps — Get the Mental Model Right First

The first mistake teams make is treating CDS Hooks like a variant of SMART on FHIR. They are fundamentally different interaction models.

A SMART app waits to be invoked. The user clicks a button, the app launches in a panel or a new window, and the user interacts with it deliberately. Your app controls the UX.

A CDS Hook interrupts. The EHR fires your hook based on a workflow event the user triggered for a completely different reason. You are not building an app — you are building a backseat driver for the EHR. Your service has to deliver value in the context of whatever the clinician was already doing, in the two seconds they have before they move on.

This changes everything about how you think about your output. The card is not a mini-app. It is a nudge, a flag, or a suggested action — nothing more.

2. You Get a Card. That Is Your Entire UI Surface.

Forget everything you know about interface design. In CDS Hooks, your rendering surface is a card. Cards have:

  • A summary (short text, shown as the card header)
  • A detail section (markdown, often truncated)
  • A source attribution
  • Optional suggestion buttons (discrete actions the EHR can execute)
  • An optional link to launch a SMART app or external resource

That is it. The art is cramming everything clinically useful into that rectangle without triggering immediate dismissal. Every character of your summary text matters. If the clinician cannot understand what action to take in two seconds, your card will be dismissed and ignored — which is functionally identical to never having fired.

Design your cards before you build your service. Get clinician feedback on the card language before you write a line of backend code.

3. Hook Timing Is Controlled by the EHR, Not You

The CDS Hooks spec defines named hooks — patient-view, order-sign, order-select, encounter-start — and the EHR fires your service when those events occur. In theory, this means predictable timing. In practice, EHRs fire hooks at moments that feel arbitrary.

A sepsis risk alert that fires during patient-view might appear while the provider is documenting a flu shot. A medication interaction alert fired on order-sign might surface after the provider has already mentally committed to the order. Timing mismatches do not just reduce effectiveness — they actively erode clinician trust in your service.

The fix is to design your hook selection around clinical workflow reality, not spec semantics. Talk to providers about exactly what they are doing at each moment before you pick a hook. Then design your alert logic to handle gracefully the cases where you fire at the wrong time — if context suggests the alert is irrelevant, suppress it rather than show noise.

4. Every Hospital Configures Hooks Differently

Build a CDS Hook for Hospital A and there is a good chance it is broken at Hospital B — even if both are running the same EHR version.

Epic, for example, allows each organization to configure how and when CDS Hooks fire, which hooks are enabled, what prefetch data gets included, and whether CDS Hook responses are given trust to execute suggestions. Hospital A might send a rich prefetch bundle with complete medication history. Hospital B might send the same hook request with no prefetch at all. Hospital C may have configured custom behaviors that interfere with your response parsing.

This is not a bug in the spec. It is intended flexibility that became a compatibility nightmare in practice.

The operational reality: treat each new site deployment as a distinct integration. Build your service to degrade gracefully when prefetch data is missing. Log what you actually receive at each site, not what the spec says you should receive. Budget for a per-site validation engagement with each new customer.

5. The Write-Back Feature Nobody Uses

CDS Hooks has a feature called suggestions — discrete actions your card can propose that the EHR can execute on the clinician's behalf. These can include writing data back to the patient record: adding a problem to the problem list, updating a medication, documenting a finding.

It is theoretically powerful. Almost nobody ships it in production, and for good reason: if your service writes bad data into a patient record, you own the clinical liability for what happens next. The cost-benefit analysis collapses quickly when you run it seriously.

If you are considering write-back, consult your malpractice counsel before you build it. The FHIR-based actions system is well-specified but the legal surface around automated clinical documentation is not. Start with read-only cards and links. Save write-back for workflows where the clinical action is clearly defined, reversible, and audited.

6. EHR Adoption Is Still Uneven — Know Your Target Before You Build

HTI-2 mandates CDS Hooks support by 2028. In 2026, adoption across EHR vendors ranges from robust to nominal.

Epic supports CDS Hooks, but with caveats: configuration is org-by-org, some hooks behave differently than the spec describes, and the prefetch implementation has historically been inconsistent. Oracle Health (formerly Cerner) supports a subset of hooks with varying fidelity depending on the product line. Smaller EHR vendors may list CDS Hooks as a supported feature while offering an implementation that breaks on non-trivial requests.

Before you commit to CDS Hooks as your integration strategy, confirm with your target customers:

  1. Which EHR and which version they are running
  2. Whether CDS Hooks are enabled in their instance
  3. Whether they have a technical team that can manage the configuration on their side
  4. Whether their EHR vendor's CDS Hooks implementation has known limitations relevant to your use case

Do this before scoping. Discovering that your target hospital cannot actually run your integration after three months of development is an avoidable failure mode.

7. Alert Fatigue Is Real and Your Hook Will Contribute to It

Clinicians are already drowning in alerts. Epic alone surfaces hundreds of advisories per provider per day in busy inpatient environments. The research on alert fatigue is unambiguous: when alert volume exceeds a threshold, override rates approach 90-95% across the board, including for genuinely important alerts.

Your CDS Hook will land in that environment. If it fires too broadly, it will be dismissed reflexively alongside everything else. If it fires on the same clinical condition that the EHR already surfaces a native alert for, some hospitals will turn your hook off entirely because they trust the native advisories more.

Design for precision. It is better to fire your hook correctly in 20% of target cases than to fire it in 100% and have it ignored. Define explicit suppression logic: if the EHR's native advisory already covers the condition, do not duplicate. If the clinical context suggests the recommendation is already addressed, suppress. Measure your dismissal rate — a high dismissal rate is a signal that your hook is firing in wrong context, not that clinicians are wrong.

8. August 2024: Epic's SMART App Launch Cards Changed the Game

In August 2024, Epic released support for CDS Hooks cards that can launch SMART apps directly. Before this, a card could show a warning but the clinician had to dismiss the card, navigate to the app launcher, find the app, and open it manually — breaking the workflow entirely.

With Launch Cards, your card can include a button that opens your SMART app inline without the user leaving the current workflow. This is the integration model that CDS Hooks should have shipped with from the start, and its arrival makes the combined CDS Hooks + SMART on FHIR pattern significantly more viable for complex workflows.

If you are building a CDS Hook that needs more UI surface than a card provides — risk stratification tools, complex order entry workflows, documentation assistance — the Launch Card pattern is now your primary architecture option. Design for it.

9. Your Response Time Budget Is 5 Seconds or You Get Timed Out

The CDS Hooks spec recommends that services respond within 500ms. Epic's implementation will time out hooks that do not respond within a defined window — in some configurations as low as 5 seconds, in others somewhat longer, but always finite and always faster than you think.

This has architectural implications:

  • Any model inference, external API call, or database query in your decision path must be fast
  • Pre-compute everything you can based on the prefetch bundle
  • Cache patient-level risk scores rather than computing them on-request
  • If you are running LLM-based logic, it cannot be in the synchronous request path — you need to surface pre-computed outputs or use lightweight rule-based logic for the real-time response

Design your service architecture around the timeout budget first, then figure out what logic you can actually fit inside it.

10. The Future Is Event-Driven Clinical Decision Support

HTI-2, Practice Advisories, and the broader shift toward real-time data in care delivery are pushing clinical decision support toward event-driven architecture. CDS Hooks is the current standard expression of that direction.

It is imperfect — the vendor adoption gaps are real, the configuration variability is real, and the alert fatigue problem is real. But the underlying model of delivering decision support at the point of care, embedded in clinical workflow, is the right model. The messy part is that no one agrees on exactly how it should work yet.

Go in with eyes open. Budget conservatively — at least double your initial estimate for timeline and testing. Invest in per-site validation. Design cards for clinicians, not for engineers. Measure dismissal rates obsessively.

When it works, it is worth it. A nudge at exactly the right moment in a clinical workflow can prevent real harm. That is the goal the complexity is in service of.

Ready to Build a CDS Hooks Integration?

CDS Hooks implementations are high-stakes — misconfigured alerts, compliance gaps, and EHR incompatibilities can derail a launch. 1Putt Health specializes in FHIR-based integrations, Epic connectivity, and clinical decision support architecture. We have shipped CDS Hooks integrations across multiple EHR environments and can help you scope, design, and deliver correctly the first time.

Book a discovery call to talk through your integration requirements.