CDS Hooks: HL7 Clinical Decision Support Specification, Workflow Hooks, JSON Cards, Prefetch Templates, and SMART on FHIR

CDS Hooks is an HL7 International standard specification that enables Electronic Health Records (EHRs) to invoke external Clinical Decision Support Systems (CDSS) synchronously at specific clinician workflow events via RESTful JSON web services. Co-developed by HL7 and the SMART Health IT project at Boston Children’s Hospital, CDS Hooks complements SMART on FHIR: whereas a SMART on FHIR app must be launched manually by a user inside the EHR, CDS Hooks runs invisibly in the background when a clinical event occurs (a “hook”) and returns actionable guidance (“cards”)—including one-click order modifications or contextual SMART app launch links—directly into the clinician’s screen.

What Is CDS Hooks?

CDS Hooks is a vendor-agnostic, synchronous HTTP POST webhook protocol in which an EHR (the CDS Client) notifies a registered external decision support server (the CDS Service) of a real-time clinical workflow action, passes contextual HL7 FHIR resources, and renders returned JSON decision cards inside the native EHR interface within sub-second latency budgets.

Before CDS Hooks, integrating clinical decision rules into enterprise EHRs required either rewriting rules in proprietary vendor languages (such as Epic BestPractice Advisories or Cerner Discern Expert CCL rules) or requiring clinicians to manually open third-party web applications. CDS Hooks decouples clinical knowledge execution from the underlying EHR database through a three-step RESTful lifecycle:

1. Service Discovery (GET {baseUrl}/cds-services): When an EHR administrator registers a CDS Service endpoint, the EHR queries its Discovery URL. The CDS Service returns a JSON catalog listing each hosted service’s unique id, the specific workflow hook it listens to, a human-readable title and description, and optional prefetch FHIR query templates.
2. Hook Invocation (POST {baseUrl}/cds-services/{id}): When a clinician performs the hooked action inside the EHR, the EHR sends an HTTP POST request signed with a JSON Web Token (JWT using RS256 or ES256) in the Authorization: Bearer header. The JSON body includes hookInstance (a UUID), hook, fhirServer (the EHR’s base FHIR URL), fhirAuthorization (a short-lived OAuth 2.0 access token), context, and prefetch data.
3. Card Rendering & Feedback (POST {baseUrl}/cds-services/{id}/feedback): The CDS Service evaluates the clinical logic and responds with a JSON array of cards (and optional systemActions in CDS Hooks 2.0). When the clinician accepts a suggestion or selects an override reason, the EHR posts a feedback payload back to the CDS Service for audit logging and continuous quality improvement.

Standard HL7 CDS Hooks Workflow Triggers

The HL7 CDS Hooks specification standardizes specific clinical workflow events so a single external service can operate across Epic, Oracle Health (Cerner), MEDITECH, and FHIR-native EHR platforms via standardized EHR integration:

Hook Name	EHR Workflow Trigger Event	Required context Fields	Primary Clinical & Research Use Cases
patient-view	Clinician opens a patient’s chart (at most once per user session).	userId, patientId, optional encounterId	Care gap reminders, clinical trial eligibility screening alerts, chronic disease risk scores, immunization prompts.
order-select	Clinician selects one or more orders (medications, labs, imaging) from the order catalog before filling out dosage/details.	userId, patientId, selections (FHIR IDs), draftOrders (FHIR Bundle)	Early formulary nudges, therapeutic substitution suggestions, duplicate lab order prevention.
order-sign	Clinician clicks to sign fully populated draft orders, immediately prior to legal order commitment.	userId, patientId, draftOrders (FHIR Bundle of MedicationRequest, ServiceRequest, etc.)	Drug-drug and renal dosing safety alerts, radiology appropriateness (AUC), and HL7 Da Vinci CRD prior authorization checks.
encounter-start & encounter-discharge	Patient admission/check-in begins or inpatient discharge workflow is initiated.	userId, patientId, encounterId	Sepsis/VTE prophylaxis protocols on admission; discharge medication reconciliation and follow-up care plans.

Anatomy of a CDS Hooks Response Card and SMART on FHIR Handoff

A CDS Service returns a JSON object containing a cards array (returning an empty array {"cards": []} when no alert is warranted to prevent alert fatigue). Each card object contains standardized attributes that govern how the EHR displays the recommendation:

• summary (Required): A concise, one-sentence plain-text statement (< 140 characters) displayed as the card headline.
• indicator (Required): Urgency level governing visual styling and interruptive vs. non-interruptive placement inside the EHR: "info" (informational badge), "warning" (cautionary banner), or "critical" (hard stop or modal alert).
• source (Required): Attribution object containing label (e.g., “CPIC Pharmacogenomics Guideline” or “NCCN Protocol”), optional url, icon, and topic so clinicians can verify provenance under ONC HTI-1 DSI transparency rules.
• detail (Optional): GitHub Flavored Markdown providing the patient-specific clinical rationale, laboratory values, or literature citation supporting the card.
• suggestions (Optional): An array of actionable button options. Each suggestion contains an actions array ("create", "update", or "delete") carrying pre-populated HL7 FHIR R4 resources (such as replacing a contraindicated MedicationRequest or adding a baseline creatinine ServiceRequest) that the clinician can execute with a single click.
• links (Optional — SMART on FHIR Launch): An array of link objects with type: "absolute" (external reference URL) or type: "smart". A "smart" link embeds a launch URL and appContext string, enabling the clinician to launch an interactive SMART on FHIR application (such as an HL7 Da Vinci DTR prior authorization questionnaire or a clinical trial enrollment consent module) directly from the CDS card without re-authenticating.

Prefetch Templates vs. Direct FHIR Server Queries

Because synchronous clinical workflow hooks (`patient-view`, `order-sign`) must execute in under 500 to 1,000 milliseconds to avoid freezing the clinician’s ordering screen, round-trip network latency is the primary engineering constraint in CDS Hooks deployments.

To eliminate extra HTTP round-trips back to the EHR’s FHIR server, CDS Services declare prefetch templates in their Discovery response using parameterized FHIR REST search syntax with {{context.patientId}} tokens:

{
  "id": "pgx-order-check",
  "hook": "order-sign",
  "title": "Pharmacogenomic CYP2C19 Order Check",
  "prefetch": {
    "patient": "Patient/{{context.patientId}}",
    "observations": "Observation?patient={{context.patientId}}&code=http://loinc.org|51274-8"
  }
}

When the EHR fires the order-sign hook, it resolves those queries locally against its internal database and attaches the resulting FHIR resources inside the prefetch key of the initial POST request. Only when an EHR omits an optional prefetch key—or when a complex clinical rule requires conditional follow-up data—does the CDS Service fall back to querying fhirServer directly using the temporary fhirAuthorization.access_token.