Short answer: CDS Hooks is an HL7 standard that lets an EHR call an external clinical decision support service at defined moments (hooks) in a clinician's workflow: opening a patient's chart (patient-view), choosing an order (order-select), signing orders (order-sign), starting or ending an encounter. The EHR sends the context and, optionally, prefetched FHIR data; the service answers within seconds with cards: short pieces of information, warnings or suggestions, and links that can launch a SMART on FHIR app. The clinician stays in the EHR; the intelligence lives outside it.
The three steps
CDS Hooks works in three steps. First, discovery: the EHR fetches GET /cds-services and learns which hook each service answers and which FHIR data it wants prefetched. Second, the hook call: at a workflow event such as order-sign, the EHR POSTs context and prefetched resources to the service. Third, the response: the service returns cards that the EHR displays.
1. Discovery. The EHR fetches GET https://cds.example.org/cds-services and receives the list of services, each with the hook it responds to and the FHIR queries it would like prefetched:
{
"services": [{
"id": "renal-dosing",
"hook": "order-sign",
"title": "Renal dosing check",
"description": "Flags drug orders whose dose needs review against the latest eGFR.",
"prefetch": {
"patient": "Patient/{{context.patientId}}",
"egfr": "Observation?patient={{context.patientId}}&code=http://loinc.org|98979-8&_sort=-date&_count=1"
}
}]
}
2. The hook call. When the clinician signs orders, the EHR POSTs to /cds-services/renal-dosing:
{
"hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
"hook": "order-sign",
"fhirServer": "https://ehr.example.org/fhir",
"fhirAuthorization": {"access_token": "…", "token_type": "Bearer", "expires_in": 300, "scope": "patient/*.read", "subject": "renal-dosing"},
"context": {
"userId": "Practitioner/42",
"patientId": "123",
"draftOrders": {"resourceType": "Bundle", "entry": [{"resource": {"resourceType": "MedicationRequest", "id": "draft-1", "status": "draft"}}]}
},
"prefetch": {
"patient": {"resourceType": "Patient", "id": "123"},
"egfr": {"resourceType": "Bundle", "type": "searchset", "entry": [{"resource": {"resourceType": "Observation", "id": "obs-9", "status": "final", "code": {"coding": [{"system": "http://loinc.org", "code": "98979-8"}]}, "valueQuantity": {"value": 38, "unit": "mL/min/1.73m2"}}}]}
}
}
If something the service needs was not prefetched, it can query the EHR's FHIR server itself with the short-lived token in fhirAuthorization.
3. The response. Cards, and in version 2.0 also system actions:
{
"cards": [{
"uuid": "9a1d2f3e-…",
"summary": "eGFR 38: dose review suggested",
"indicator": "warning",
"detail": "The most recent eGFR (38 mL/min/1.73m², 2026-03-10) is below the threshold in the local renal dosing guidance for this drug.",
"source": {"label": "Hospital renal dosing guidance", "url": "https://intranet.example.org/renal"},
"suggestions": [{"label": "Open renal dosing table", "uuid": "…", "actions": []}],
"links": [{"label": "Dosing calculator", "url": "https://apps.example.org/renal/launch", "type": "smart"}]
}]
}
summary is limited to 140 characters; indicator is info, warning or critical; source is mandatory so the clinician knows who is talking. suggestions may propose concrete changes (create, update or delete a draft resource) that the clinician accepts with one click; links of type smart open a SMART app in context. The EHR renders the cards in its own style; the service never draws its own UI inside the EHR.
Version 2.0 additions
CDS Hooks version 2.0, published in 2022, added a feedback endpoint through which the EHR reports whether a card was accepted, overridden with reasons or ignored; systemActions, changes the EHR applies without asking, for low-risk housekeeping; the fhirAuthorization.subject field; and clearer selectionBehavior rules (at-most-one or any) for suggestions.
Published in 2022: a feedback endpoint (POST /cds-services/{id}/feedback) through which the EHR reports whether a card was accepted, overridden (with reasons) or ignored; systemActions, changes the EHR applies without asking, meant for low-risk housekeeping such as adding a coded reason; fhirAuthorization.subject; and clearer rules on selectionBehavior (at-most-one or any) for suggestions.
What a service is, and is not
A CDS Hooks service is software that reads workflow context and returns information as cards; it is not automatically a medical device. Whether medical device rules apply in the EU and the US depends on the content: reminding a clinician that a lab value exists is information, whereas a patient-specific dose recommendation is regulated decision support.
A CDS service is software that reads context and returns information. Whether it is a medical device depends on what the cards say: a reminder that a lab value exists is information; a dose recommendation for a specific patient is decision support that falls under medical device rules in the EU and the US. See Is a health app a medical device?. The standard is neutral; the content is not.
Hooks defined today: patient-view, order-select, order-sign, order-dispatch, encounter-start, encounter-discharge, appointment-book, with a public catalogue where new hooks are proposed.
Relation to SMART on FHIR
CDS Hooks and SMART on FHIR are complementary. SMART on FHIR launches an app that takes over part of the screen and queries the FHIR server with the user's authorisation; CDS Hooks runs in the background and returns cards into the EHR's own interface. A card can carry a SMART launch link when more than a card is needed.
SMART on FHIR launches an app that takes over part of the screen and talks to the FHIR server with the user's authorisation. CDS Hooks runs in the background and returns cards; a card can carry a SMART launch link when more than a card is needed. Most decision-support products use both: hooks for the nudge, a SMART app for the detail.
Where Anpheros fits
Anpheros does not offer a CDS Hooks service and does not produce clinical recommendations. Its FHIR record, with the patient's consent, can be the data a hospital's own decision-support service reads (medications, allergies, recent results), through the same FHIR API a hook service would use. See Patient consent platform.
Related pages
- FHIR Subscriptions explained
- Is a health app a medical device? EU MDR Rule 11
- Patient consent platform
- FHIR search explained
- SMART on FHIR backend (developers)
- Healthcare interoperability standards: the map
- SMART App Launch explained
Sources
- HL7 CDS Hooks specification 2.0
- CDS Hooks: hook catalogue
- HL7 SMART App Launch
- HL7 FHIR R4: MedicationRequest
Frequently asked questions
Is CDS Hooks part of FHIR?
It is a separate HL7 specification that uses FHIR for its data: prefetch and context carry FHIR resources, and authorisation reuses SMART on FHIR tokens. It is published by HL7 alongside FHIR, not inside the FHIR specification.
How fast must a CDS service answer?
The specification does not fix a number, but EHRs apply timeouts of a few seconds and discard late responses, because the clinician is waiting. Prefetch exists precisely so the service does not spend that time querying.
Can a CDS service change the order?
Only by proposing a suggestion the clinician accepts, or, in 2.0, through systemActions the EHR has agreed to apply automatically for that service. The service never writes to the EHR's FHIR server on its own during a hook.
Does a patient app use CDS Hooks?
No. CDS Hooks is designed for clinician-facing EHR workflows. Patient apps use the FHIR API directly and SMART on FHIR for login.
Try it free in the sandbox
Your first FHIR call in 5 minutes. An HL7 FHIR R4 API with the patient's consent built in: try it in the sandbox, then connect your own app or clinic system.
Free · 30 synthetic patients · no card
Anpheros builds a medical record that the patient controls and can share with any clinic, on an HL7 FHIR R4 platform, based in the EU. These guides help you understand and organise your health; they do not replace your doctor.
About Anpheros →
AnpherosThe more you log, the clearer your record
Your health history in one place, under your control.
Free · Works in your browser · No card
