CDS Hooks: shipping clinical decision support clinicians actually use

CDS Hooks is the HL7 standard for showing decision support inside the EHR at the moment it matters. The standard gets your card on screen; whether clinicians act on it depends on when it fires, what it says and how you measure it.

In short

  • CDS Hooks is an HL7 standard (current published release 2.0.1) that lets an EHR call your decision support service at a set point in the clinician's workflow, such as opening a chart or signing an order, and display your advice as short cards.
  • Clinicians act on cards that fire at the right moment, are specific, offer a one-click suggestion and show the basis for the advice, and the spec's feedback endpoint tells you which cards are accepted or overridden.
  • Before launch, check which hooks each EHR supports, whether FDA's January 2026 clinical decision support guidance treats your logic as a device, and what source information health systems will ask for.

CDS Hooks is an HL7 standard that lets an EHR call your decision support service at a set moment in the clinician's workflow, such as opening a chart or signing an order, and show your advice as short cards. Clinicians use it when the cards are rare, specific, actionable and explain their basis, and tune it out when it interrupts often with generic advice.

This guide is for product leads building decision support for US clinicians and for clinic IT teams evaluating it.

What is CDS Hooks?

The specification describes a hook-based pattern for invoking decision support from within a clinician's workflow. A hook is a named step, such as patient-view when a chart is opened, order-select when orders are chosen, or order-sign immediately before an order is signed. When the hook fires, the EHR calls your service with context about the patient and the action, and your service answers in near real time.

The current published release on cds-hooks.hl7.org is 2.0.1, a trial-use (STU) release based on FHIR R4. The spec does not prescribe a default or required set of hooks; hook definitions live in the companion CDS Hooks Library and mature as implementers use them. A hook reaches the top maturity level only once it runs in production in at least two EHRs and three independent services.

How does a CDS Hooks call work?

  • Discovery: your service publishes the hooks it handles at {baseUrl}/cds-services. The spec says this endpoint shall always be available.
  • Context: when a hook fires, the EHR sends the workflow data that hook defines, such as the user, the patient and any draft orders.
  • Prefetch: your service can declare FHIR queries it wants answered up front. The EHR may honor zero, some or all of them, so your service must be able to fetch the rest itself.
  • Data access: when the EHR passes a FHIR access token, the spec says to treat it as transient and not store it.
  • Response: your service returns zero or more cards.
  • Feedback: the EHR can report back to {baseUrl}/cds-services/{id}/feedback whether each card was accepted or overridden, with a timestamp.

Security is defined too. The EHR authenticates to your service with a signed JWT. The spec forbids the none algorithm and symmetric signing, and recommends ES384 or RS384.

What goes on a card?

{
  "cards": [{
    "uuid": "b3a1c0de-0000-4000-8000-000000000001",
    "summary": "eGFR 28: consider dose reduction for this order",
    "indicator": "warning",
    "source": { "label": "Renal dosing rules v3" },
    "suggestions": [{ "label": "Switch to reduced dose" }],
    "selectionBehavior": "at-most-one",
    "overrideReasons": [{ "display": "Dose already adjusted by nephrology" }],
    "links": [{ "label": "Open dosing calculator", "url": "https://example.org/launch", "type": "smart" }]
  }]
}
  • summary: one sentence, under 140 characters. This is often all the clinician reads.
  • indicator: info, warning or critical, in increasing urgency. The EHR may use it to sort or color cards.
  • source: required. It names where the guidance comes from.
  • suggestions: optional proposed changes the clinician can accept with one click. If present, selectionBehavior must be set (at-most-one or any).
  • overrideReasons: optional reasons a clinician can pick when declining the card.
  • links: optional links, either absolute URLs or smart links that launch a SMART on FHIR app for a longer workflow.

The spec also defines system actions, which are not shown to the user and may be applied automatically. The EHR decides whether to apply them, so do not design a product that depends on them without checking each customer.

Why do clinicians ignore decision support?

Mostly because it costs them time and gives little back. A card that fires on every chart, repeats what they already know, or asks them to leave the order screen to read a guideline gets dismissed out of habit. Once that habit forms, the one important card gets dismissed too. The spec itself warns that several services may answer the same hook with related information, so your card competes with others on the same screen.

The standard leaves the following design choices to you.

Fire on the right hook

Pick the latest moment where the advice can still change the decision. Dosing advice belongs at order-select or order-sign, when the order is in front of the clinician, not at patient-view, when they are still reading the chart.

Return nothing most of the time

Zero cards is a valid answer, and it should be your most common one. Filter on the context and prefetched data before you return anything. If the clinician has already done what you would suggest, stay silent.

Make the card specific and actionable

Put the patient-specific fact and the action in the summary: the lab value, the drug, the change. Offer a suggestion button where one exists, so accepting takes one click. Save critical for cases where harm is likely if the clinician proceeds.

Show your basis

Fill in source, and link to the rule or evidence behind the card. Clinicians trust advice they can check, and, as the next section explains, letting them check it is also one of FDA's criteria for decision support that is not a device.

Give them a way to say no

Offer override reasons that match real situations. They make declining fast, and they tell you why a card is wrong for a group of patients.

Is your clinical decision support a medical device?

Possibly. FDA issued its current Clinical Decision Support Software guidance on January 29, 2026, superseding a version issued on January 6, 2026. Under section 520(o)(1)(E) of the FD&C Act, a CDS software function is excluded from the device definition only if it meets all four criteria:

  • 1. It is not intended to acquire, process or analyze a medical image, a signal from an in vitro diagnostic device, or a pattern or signal from a signal acquisition system.
  • 2. It is intended to display, analyze or print medical information about a patient or other medical information, such as clinical studies and guidelines.
  • 3. It is intended to support or provide recommendations to a health care professional about prevention, diagnosis or treatment.
  • 4. It is intended to let that professional independently review the basis for the recommendations, so they do not rely primarily on them for a diagnosis or treatment decision.

The guidance gives examples: software that analyzes an ECG waveform or continuous glucose monitor readings does not meet criterion 1. If your logic touches signals or images, or clinicians cannot see why it recommends what it does, get a regulatory read before you build. Our SaMD service page covers what device software adds to a project.

What does ONC require from EHRs for decision support?

ONC's certification criterion §170.315(b)(11) covers decision support interventions in certified EHRs. It separates evidence-based interventions from predictive ones, which use models derived from training data. Both must expose source attributes, a list of 13 items for evidence-based interventions such as citation, developer and funding source, and a much longer list for predictive ones covering intended use, training data, validation and monitoring. Users must be able to give feedback, and that feedback must be exportable.

The criterion applies to EHR developers, not directly to your service. But a health system that configures its EHR under these rules will expect you to supply the same kind of information about your logic. Write it down before the first meeting.

Do Epic and Cerner support CDS Hooks?

Epic's FHIR developer site lists CDS Hooks among its API listings, labeled for R4 and STU3. For Oracle Health (Cerner) clinical decision support, we could not find a current public list of supported hooks in its developer documentation, so ask the vendor and the customer directly.

Whatever the vendor, confirm three things with each customer: which hooks are turned on, how cards are displayed (the spec lets the EHR hide details of non-urgent cards until clicked), and whether the EHR sends feedback. Card display and feedback are EHR decisions, and they change how your service behaves for clinicians.

How do you measure whether clinicians use it?

  • Collect feedback for every card: accepted or overridden, and which override reason.
  • Report by card type and by department instead of one average, because one noisy rule can hide several good ones.
  • Track how often each rule returns a card at all. A rule that fires on most charts needs tighter filters.
  • Review the numbers with a clinical champion on a fixed schedule, and retire cards that are overridden most of the time.
  • If the EHR does not send feedback, log what you returned and compare it with orders signed afterward.

How should you roll out a CDS Hooks service?

  • Start with one rule, one hook and one department, with a named clinical owner.
  • If the EHR allows, run the service in the background first and log the cards it would have shown. Review them with clinicians before anyone sees one.
  • Turn cards on for a pilot group, watch feedback weekly, and fix or remove the noisy ones.
  • Expand only after the pilot group accepts most of what it sees.
  • Use a SMART app link instead of a long card when the decision needs more than one screen.

Privacy rules apply to decision support too. We sign a BAA before touching PHI, run penetration tests before launch, and scope access so each clinician sees only their own patients. When we build AI assistants for clinical teams, they cite their sources and run on Claude via AWS Bedrock or Anthropic directly.

If you are designing a CDS Hooks service and want an engineer's read on hooks, card design and the regulatory questions, talk to one of our engineers. Our 5-day free technical audit ends with a written report.