CDS Hooks is a vendor-neutral, HL7 FHIR based REST API that lets electronic health records call external CDS Services in real time and receive cards: information, suggestions, app links, or systemActions. The specification, now at version 2.0.1, with v3.0 in ballot, defines three core APIs: Discovery, Service, and Feedback. Platforms build around these same principles when connecting clinical decision support to real workflows.
TL;DR:
- Discovery runs once or refreshes periodically, while the Service endpoint fires at each matching workflow event, making payload size and response time important.
- Start with chart opening for low risk informational cards, use order selection for nonblocking guidance, and reserve signing checks for genuine safety risks.
- Prefetch recurring data such as active conditions and medications; query the FHIR server directly only when the data varies too much to template.
- Keep responses near the recommended 500 millisecond budget by narrowing FHIR queries and parallelizing lookups; test in silent mode before showing cards live.
- Feedback is optional, but recording whether clinicians accept or override a specific card gives services evidence for improving later suggestions.
Table of Contents
- Understanding the core anatomy of the CDS Hooks specification
- How discovery, service, and feedback payloads actually work
- Common hooks and what they look like in practice
- Securing the connection and getting prefetch right
- Performance targets that protect the clinical workflow
- From prototype to production: a sandbox-first rollout
- How an integrated platform approaches CDS Hooks in practice
- A faster path for teams that don't want to build their own CDS Service
- FAQ
- Sources
Understanding the core anatomy of the CDS Hooks specification
Every CDS Hooks implementation revolves around three actors: the CDS Service, which contains the actual decision logic; the CDS Client, typically the EHR, which calls that service at defined trigger points; and the Card, the structured response the service sends back. The CDS Hooks specification defines a Discovery endpoint where a CDS Client finds out what services are available and what each one needs to run.
Cards carry a defined set of fields: summary, indicator (info, warning, or critical), detail, source, an optional suggestions array, and optional links for launching external apps. Since the 2.0 series, cards can also include systemActions, which let a service propose changes the EHR applies automatically rather than presenting them for manual review.
A few anchor points worth bookmarking:
- The current stable release is CDS Hooks 2.0.1 (STU 2), with version 3.0 currently in balloting.
- The Hook Library inside the HL7 implementation guide catalogs every defined hook and its trigger context.
- Discovery responses list each service's
id,hook,title, andprefetchtemplate.
How discovery, service, and feedback payloads actually work
The three APIs handle distinct jobs, and each has its own required fields. Discovery tells the CDS Client what exists. The Service API carries the actual clinical context and returns cards. Feedback closes the loop by reporting what clinicians did with a suggestion.
| API | Direction | Key fields | Purpose |
|---|---|---|---|
| Discovery | EHR requests from service | id, hook, title, prefetch | Lists available CDS Services and their requirements |
| Service | EHR sends to service | hook, hookInstance, context, fhirServer, prefetch | Delivers clinical context and triggers decision logic |
| Feedback | EHR sends to service | card, outcome, outcomeTimestamp | Reports whether a suggestion was accepted or overridden |
A Service request always includes hook (the hook name), hookInstance (a UUID unique to that invocation), and context (the clinical data specific to that hook). Depending on the deployment, it may also carry fhirServer and fhirAuthorization so the service can query additional resources beyond what's prefetched, plus any prefetch bundle the Discovery response asked for.
A conformant Service response is a 200 status with a cards array, where each card follows the schema from the CDS Hooks home page: summary, indicator, detail, source, and either suggestions or systemActions. The Feedback endpoint lives at {baseUrl}/cds-services/{id}/feedback and accepts outcome records tied back to a specific card, which is how a service learns whether its suggestions are actually useful rather than ignored.
- Discovery is a one-time (or periodically refreshed) call, not per-patient.
- Service requests fire on every matching workflow event, so payload size and response time both matter.
- Feedback is optional per the spec but essential for any service that wants to improve its own suggestion quality over time.
Common hooks and what they look like in practice
Three hooks cover most real-world pilots. The patient-view hook fires when a clinician opens a patient's chart, carries a patientId in context, and suits read-only information cards like allergy alerts or care gap reminders. order-select fires as a clinician is choosing an order, with draftOrders and a selections array in context, and suits early guidance such as a cheaper formulary alternative. order-sign fires at the moment of signing, giving a CDS Service a last chance to flag a drug interaction or duplicate order before it becomes final.
Older implementations may reference medication-prescribe or order-review, both of which have been superseded by the order-select and order-sign pair; new builds should target the current hooks rather than the deprecated ones. Full request and response JSON for these scenarios, including how systemActions can update a draftOrders bundle directly, is available on the official CDS Hooks examples page.
- Start with patient-view for low-risk informational cards before touching order workflows.
- Pilot order-select for guidance that doesn't need to block signing.
- Reserve order-sign for genuine safety checks, since it sits directly in the signing path.
Pro Tip: Pilot patient-view first. It has the lowest risk of disrupting an active ordering workflow while you validate card rendering and prefetch behavior.
Securing the connection and getting prefetch right
Production CDS Hooks traffic runs over HTTPS, and Service calls from a CDS Client should carry an Authorization header with a JWT when the implementation guide requires it, as described in the HL7 artifacts and version notes. When a service needs to query the FHIR server directly rather than relying only on prefetch, the request includes an fhirAuthorization bearer token scoped to what that service is permitted to read.
Prefetch templates exist to cut latency: instead of a service making its own FHIR calls mid-request, the CDS Client resolves a predefined query template and hands over the results as part of the Service payload. This removes a network round trip from the critical path, which matters directly for meeting response-time targets.
- Use prefetch for data every invocation needs, like active conditions or current medications.
- Fall back to
fhirServerqueries only for data that varies too much to template cleanly. - Check the
usageRequirementsfield in Discovery responses, since some sites negotiate capability limits a service must respect.
Performance targets that protect the clinical workflow
The CDS Hooks best practices guidance recommends a response budget around 500 milliseconds, a target meant to keep a card appearing before the clinician has moved on to the next screen. Falling outside that window tends to reduce whether clinicians even notice or act on a suggestion.
Getting there is mostly about query discipline rather than raw infrastructure spend:
- Tighten prefetch templates with
_include,_revinclude, and date filters so the FHIR server returns only what's needed. - Parallelize independent lookups and cache anything that doesn't change within a single encounter.
- Trim the response itself: a card with a two-sentence summary beats one with a paragraph nobody reads.
Aim for a p95 latency comfortably under the 500 millisecond spec recommendation, according to the same best practices guidance, since that is what keeps engagement high rather than training clinicians to dismiss cards on reflex. Running a service in silent mode first, where cards are logged but not shown, helps confirm hook volume and relevance before clinicians see anything live.
From prototype to production: a sandbox-first rollout
A practical path from first prototype to a validated service follows the order laid out in the CDS Hooks quick start:
- Build the discovery endpoint listing your service's id, hook, and prefetch template.
- Implement the service handler and return well-formed cards for representative test cases.
- Register and test the service against the CDS Hooks Sandbox and its bundled FHIR test server.
- Add an optional SMART app link if a card should launch a deeper in-context application.
- Layer in production security: enforce HTTPS, require Authorization headers, and tune performance before connecting to a live EHR.
The sandbox is the right place to confirm card rendering and prefetch contracts against realistic patient data, since catching a malformed card there costs nothing compared to catching it in a live chart review.
How an integrated platform approaches CDS Hooks in practice
Specification compliance is only half the job. The harder part is making a suggestion trustworthy enough that a clinician actually acts on it, which is why we built Medgram around visible evidence rather than opaque alerts: every suggestion in our platform links back to the clinical reasoning behind it, not just a card with a recommendation attached.
Our EHR-side web extension and Clinical Scribe are built to complement the same kind of real-time, in-workflow pattern CDS Hooks defines, turning a conversation into structured notes without pulling a clinician out of their chart. Teams building or evaluating CDS Services may seek integration guidance grounded in day-to-day clinical use.
— Dina Abou Dargham
A faster path for teams that don't want to build their own CDS Service
Standing up a conformant CDS Service, a discovery endpoint, prefetch templates, and a feedback loop is a real engineering project, one that keeps running long after the first pilot ships. For teams that would rather get decision support and documentation tooling without owning that infrastructure, a unified alternative exists: one platform combining case management, evidence-backed suggestions, and EHR-side integration that may not require separate IT approval to pilot.
Our Clinical Decision Support Tool and Clinical Scribe cover the suggestion and documentation sides of the same workflow CDS Hooks targets, while our Chart Summarizer & Smart Handoff tool handles the handoff moment most hook-based systems leave untouched.
- See the suggestion and evidence layer in our Clinical Decision Support Tool.
- Try the documentation side with Clinical Scribe.
- Walk through both in our interactive demo.
If building and maintaining your own CDS Service isn't where you want to spend engineering time this year, request a walkthrough to see how the pieces fit together.
This article is general information, not a substitute for advice from a qualified doctor. Consult a qualified healthcare professional about your own circumstances before acting on anything here.
FAQ
What is CDS in health informatics?
Clinical decision support (CDS) refers to tools and workflows that give clinicians patient-specific guidance at the point of care, such as alerts, reminders, or reference information. CDS Hooks is one standardized way to deliver that guidance by connecting an EHR to external CDS Services in real time.
What are CDS Hooks and what are they used for?
CDS Hooks is a vendor-neutral, HL7 FHIR based API specification that lets an EHR call an external service at specific workflow moments, like opening a chart or signing an order, and display the response as a card. It is used to surface alerts, suggestions, and reference links without requiring custom integration for every EHR and service pair.
What is an example of clinical decision support?
A common example is a service triggered by the order-sign hook that checks a newly signed medication against a patient's active prescriptions and returns a card warning of a potential interaction. Another is a patient-view hook that surfaces an overdue screening reminder as soon as a clinician opens the chart.
What are hooks in coding, in the context of CDS Hooks?
In this context, a hook is a named trigger point in the clinical workflow, such as patient-view, order-select, or order-sign, that tells a CDS Client when to call an external service. Each hook defines its own context fields, so a service knows exactly what clinical data to expect when that trigger fires.
How does CDS Hooks handle security?
Production CDS Hooks traffic runs over HTTPS, and service calls typically require an Authorization header with a JWT, with an additional fhirAuthorization bearer token when a service needs direct FHIR server access. These requirements are defined in the HL7 implementation guide rather than left to individual vendors to improvise.