CDS Hooks Technical Implementation: Code, Spec, Production

1. What CDS Hooks v2.0.1 Actually Solves (and What It Does Not)

CDS Hooks v2.0.1 is the HL7 specification (current version) that defines three RESTful APIs between CDS Clients and CDS Services. Discovery for advertising services and prefetch templates. Service for handling hook invocations and returning CDS Cards. Feedback for learning outcomes. All exchanges use JSON over HTTPS.

The hook lifecycle is straightforward in description. The EHR detects a workflow event (a clinician composing or signing an order, opening a patient chart, scheduling an appointment). The EHR invokes the registered CDS Service with a hookInstance identifier, the workflow context, and the prefetched FHIR data. The service evaluates against its rules engine or model. The service returns one or more CDS Cards. The EHR renders them inline in the clinician’s screen.

What the spec does not solve. Rules engine internals. Override-reason taxonomy. Alert fatigue tuning. Clinician trust. CDS Card severity discipline. Latency budget. None of these is in the spec, and all of them are what determines whether your production deployment hits 80% provider engagement or 30% .

I see teams over-trust spec compliance and under-build the production layer. “We are spec-compliant, our cards render correctly, but only 30% of providers engage.” That is not a spec problem. The spec is the floor.

2. The Discovery Endpoint and How a Service Advertises Itself

A CDS Service publishes its capabilities through a discovery endpoint at GET /cds-services. The response is a JSON object with a services array. Each service entry declares which hook it supports, what prefetch data it needs, and how the EHR should call it.

The convention from the HL7 v2.0.1 spec and confirmed in Smile CDR’s implementation reference:

{
  "services": [
    {
      "hook": "order-sign",
      "title": "Preoperative Readiness Check",
      "description": "Verifies missing preoperative labs and surgical clearances before order signing.",
      "id": "preop-readiness-v3",
      "prefetch": {
        "patient": "Patient/{{context.patientId}}",
        "currentMedications": "MedicationRequest?patient={{context.patientId}}&status=active",
        "allergies": "AllergyIntolerance?patient={{context.patientId}}",
        "recentLabs": "Observation?patient={{context.patientId}}&category=laboratory&date=ge{{(today() - 90 days)}}"
      }
    },
    {
      "hook": "patient-view",
      "title": "Surgical Risk Snapshot",
      "id": "surgical-risk-v2",
      "prefetch": {
        "patient": "Patient/{{context.patientId}}",
        "conditions": "Condition?patient={{context.patientId}}&clinical-status=active"
      }
    }
  ]
}

Two production patterns worth naming. First, advertise each hook as a separate service entry with its own prefetch. Do not bundle multiple hooks into one service. EHR clients route to services individually and a bundled entry confuses cache behavior. Second, version your service id. When the prefetch contract changes, bump the version (preop-readiness-v3 to v4) rather than silently editing keys, because CDS Clients cache the discovery response and silent edits cause stale prefetch.

The HL7 spec also defines an optional usageRequirements field for documenting required SMART scopes or other client constraints. Worth including when the service depends on specific FHIR scopes the client must grant.

3. The order-sign Hook (Request Shape, draftOrders Bundle, FHIR Resources)

The order-sign hook fires when a clinician is ready to sign one or more orders. This is the last workflow event before an order is promoted out of draft status. It is the flagship hook for medication safety, preoperative readiness, and clinical-protocol enforcement, and it was the trigger we used for the perioperative-readiness deployment that reached 87% provider engagement.

Per the HL7 hook specification and Open.epic’s FHIR documentation, Epic supports ServiceRequest and MedicationRequest resources in the draftOrders Bundle of the order-sign hook context. Other major EHRs that support CDS Hooks follow the same pattern.

The request body the EHR sends to the CDS Service:

{
  "hook": "order-sign",
  "hookInstance": "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
  "fhirServer": "https://fhir.example-hospital.org/api/v1",
  "fhirAuthorization": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "patient/Patient.read patient/Observation.read",
    "subject": "cds-service-preop-readiness"
  },
  "context": {
    "userId": "Practitioner/example-prescriber",
    "patientId": "example-patient-001",
    "encounterId": "example-encounter-2026-05-07",
    "draftOrders": {
      "resourceType": "Bundle",
      "type": "collection",
      "entry": [
        {
          "resource": {
            "resourceType": "ServiceRequest",
            "status": "draft",
            "intent": "order",
            "code": {
              "coding": [{
                "system": "http://snomed.info/sct",
                "code": "387713003",
                "display": "Surgical procedure"
              }]
            },
            "subject": { "reference": "Patient/example-patient-001" }
          }
        }
      ]
    }
  },
  "prefetch": {
    "patient": { "resourceType": "Patient", "id": "example-patient-001", "...": "..." },
    "currentMedications": { "resourceType": "Bundle", "...": "..." },
    "allergies": { "resourceType": "Bundle", "...": "..." },
    "recentLabs": { "resourceType": "Bundle", "...": "..." }
  }
}

Three implementation notes worth flagging.

The hookInstance is a globally unique, un-guessable identifier that the EHR generates per hook invocation. The CDS Service should use it for idempotency. A clinician who hits Sign, sees the card, dismisses it, and re-Signs will trigger a fresh hookInstance; the service stores the prior outcome and returns the same card structure on retry rather than confusing the clinician with new wording.

The draftOrders Bundle holds the orders being signed. For order-sign on a single medication, the Bundle has one MedicationRequest entry. For a complex preoperative order set, the Bundle can hold a ServiceRequest plus several MedicationRequest entries. The service iterates the Bundle entries and applies its rules to each.

The fhirAuthorization object carries the OAuth 2.0 bearer token the CDS Service uses if it needs to fetch additional FHIR resources beyond what prefetch delivered. We will cover the auth mechanics in H2 #5.

A piece dedicated to medication-safety CDS in this same architectural pattern lives at medication safety clinical decision support.

4. Prefetch Contract Design (Where Most Builds Get Stuck)

Prefetch is the design decision that makes or breaks production performance. Get it wrong and your latency budget blows past 1 second and cards never render in time. Get it right and the service hits sub-300-ms end-to-end with 87% engagement.

The HL7 v2.0.1 spec uses simple substitution syntax for prefetch templates: {{context.patientId}}, {{context.encounterId}}. Worth knowing the limitation: per GitHub issue #377 in cds-hooks/docs, prefetch tokens currently support only top-level context elements expressed as simple key-value pairs. They cannot use context information passed as resources (the draftOrders Bundle, for example). If your prefetch needs to filter on something inside draftOrders, fall back to fhirAuthorization and have the service fetch.

Failure handling has three modes per spec:

1. Mode 1: Prefetch satisfied. The CDS Client returns the prefetch object with all keys populated. The service uses the data directly.
2. Mode 2: Prefetch partial. The CDS Client returns the prefetch object with one or more keys missing or null. The service decides per key whether to proceed without that data, fall back to the EHR’s FHIR API using fhirAuthorization, or reject the request.
3. Mode 3: Prefetch insufficient. The service determines required data is missing and the request did not include fhirAuthorization for fallback. The spec instructs the service to respond with HTTP 412 Precondition Failed.

The production trade-off. Minimal prefetch plus service-side fetch trades latency for flexibility (and adds round-trips). Rich prefetch trades CDS Client load for service-side speed (and requires the client to honor every template).

The pattern we landed on for the perioperative-readiness build:

• Pull MedicationRequest (active), AllergyIntolerance, Observation (renal function and recent labs), and Condition (active) in prefetch
• Fall back to fhirAuthorization for anything optional or rare (specific historical labs, family history, social determinants)
• Latency budget under 500 ms end-to-end (EHR hook trigger to card render)
• Actual measured latency averaged 280 ms with prefetch-only path, 540 ms with fhirAuthorization fallback path

Per HL7 spec recommendations: prefetch queries should use instance-level read interactions and token search parameters with equality (optionally with the :in modifier). Date search parameters should use specific prefixes only. Avoid wildcards and complex chained search; CDS Clients vary in what they actually support.

5. Authentication: JWT, JWS, and the fhirAuthorization Bearer Token

Two authentication patterns operate concurrently in CDS Hooks. They serve different purposes and teams often confuse them.

Pattern 1: CDS Client to CDS Service authentication. Per HL7 v2.0.1 spec, every request from a CDS Client to a CDS Service MUST include an Authorization header presenting a JWT as a Bearer token. This applies to Discovery calls, Service invocations, and Feedback. The JWT is signed using JWS (JSON Web Signature). The CDS Service verifies the signature using the CDS Client’s public keys, typically published at a jku URL referenced in the JWT header.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...

The CDS Service must:

• Extract the JWT from the Authorization header
• Resolve the jku (JWK Set URL) from the JWT header
• Fetch the JWK Set from that URL (cache the keys with a short TTL, 60 minutes is reasonable)
• Verify the JWS signature using the matching kid
• Validate iss (issuer matches the registered CDS Client), aud (audience matches your service URL), and exp (not expired)

Key rotation discipline matters. CDS Clients rotate signing keys. A service that hardcodes a single public key, then breaks the day the client rotates, is a real production failure mode. Refresh the JWK Set on signature verification failure before rejecting calls; rotate gracefully.

Pattern 2: CDS Service to FHIR Server authentication. When the CDS Service needs to fetch additional FHIR resources from the EHR’s FHIR server (the prefetch fallback case), the CDS Client passes an OAuth 2.0 access token in the fhirAuthorization object inside the request body:

"fhirAuthorization": {
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "patient/MedicationRequest.read patient/Observation.read",
  "subject": "cds-service-preop-readiness",
  "patient": "example-patient-001"
}

The service uses access_token as a Bearer token in any subsequent FHIR API call back to the EHR’s FHIR server (fhirServer URL in the request body). The token is short-lived (typically 5 minutes per the expires_in: 300 example above). The token’s scope declares which FHIR resources the service is authorized to read. The optional patient field carries the SMART context where applicable.

The trap. Treating Pattern 1 and Pattern 2 as the same token. They are different tokens issued by different parties for different purposes.

6. The CDS Card Response: Cards, Source, Suggestions, Links, and overrideReasons

The response shape determines whether clinicians engage with your output or override 90% of cards by reflex.

The response body is JSON with two top-level arrays: cards and (optional) systemActions.

{
  "cards": [
    {
      "summary": "Missing CBC required for elective cardiac surgery",
      "indicator": "warning",
      "detail": "Surgical protocol for elective cardiac procedures requires CBC within 14 days of OR date. Patient's most recent CBC is 28 days old. Order CBC before signing surgical orders.",
      "source": {
        "label": "Institutional Preoperative Protocol v3.2",
        "url": "https://example-hospital.org/protocols/preop-cardiac-v3-2",
        "icon": "https://example-hospital.org/assets/protocol-icon.png"
      },
      "suggestions": [
        {
          "label": "Add CBC to current orders",
          "uuid": "abc-123-cbc-suggestion",
          "actions": [
            {
              "type": "create",
              "description": "Add CBC ServiceRequest to draft orders",
              "resource": {
                "resourceType": "ServiceRequest",
                "status": "draft",
                "intent": "order",
                "code": {
                  "coding": [{
                    "system": "http://loinc.org",
                    "code": "58410-2",
                    "display": "Complete blood count panel"
                  }]
                },
                "subject": { "reference": "Patient/example-patient-001" }
              }
            }
          ]
        }
      ],
      "overrideReasons": [
        { "code": "clinically-appropriate", "system": "https://example-hospital.org/cds/override-codes", "display": "Clinically appropriate to proceed without CBC" },
        { "code": "patient-already-has", "system": "https://example-hospital.org/cds/override-codes", "display": "Patient has recent equivalent results outside this EHR" },
        { "code": "monitoring-planned", "system": "https://example-hospital.org/cds/override-codes", "display": "Will obtain CBC during pre-anesthesia visit" },
        { "code": "alternative-plan", "system": "https://example-hospital.org/cds/override-codes", "display": "Alternative monitoring plan in place" },
        { "code": "low-risk-this-patient", "system": "https://example-hospital.org/cds/override-codes", "display": "Low risk for this specific patient" },
        { "code": "deferred-pharmacist", "system": "https://example-hospital.org/cds/override-codes", "display": "Deferred to pharmacist review" },
        { "code": "other", "system": "https://example-hospital.org/cds/override-codes", "display": "Other (free text required)" }
      ],
      "links": [
        {
          "label": "View full preoperative protocol",
          "url": "https://example-hospital.org/protocols/preop-cardiac-v3-2",
          "type": "absolute"
        }
      ]
    }
  ]
}

Card field discipline:

• summary is human-readable and required to be 140 characters or fewer per spec. This is the card’s headline; it must communicate the action without context.
• indicator is one of info / warning / critical. Map these to actual workflow consequence: critical means hard stop with co-sign requirement, warning is interruptive with structured override, info is non-interruptive chart annotation.
• detail is Markdown-formatted. Use it for the rule citation and the patient-specific reasoning.
• source is required and carries the institution-specific protocol reference or evidence source. Always populate; never leave empty.
• suggestions is the structured action the EHR can apply with one click on behalf of the clinician. Each suggestion has a uuid and an actions array describing FHIR-resource modifications.
• overrideReasons is the lever that makes override-reason data tunable. Use a structured fixed list of 5 to 10 codes. Free text only as a fallback option that requires explicit selection.
• links carries reference URLs (absolute or SMART app launches per type).

Per the HL7 spec, the EHR may apply suggestion actions one-click on the clinician’s behalf. The uuid is what the EHR sends back via the Feedback API to learn which suggestions clinicians accepted. That feedback loop is how you tune the rules engine over time.

The same Card structure feeds the order-select hook used by ordering-physician-facing radiology CDS, covered in our radiology clinical decision support walkthrough.

7. Production Lessons from a Perioperative-Readiness CDS Hooks Deployment

Spec compliance was the first month. The next three months were CDS Card tuning, override-reason taxonomy iteration, prefetch contract latency optimization, and clinician feedback-loop integration. The deployment reached 87% provider engagement (clinicians actively interacting with cards rather than dismissing them) and reduced missed preoperative labs from 15% to 2% . The work that earned those numbers happened after spec compliance, not during it.

Five lessons worth naming.

1. Lesson 1: Card severity tier discipline. Three tiers map to actual workflow consequence. Critical means a hard stop with required co-sign before the order commits. Warning is an interruptive popup with structured override required. Info is an inline chart annotation, never interruptive, never blocking. We started with too many warnings; the override rate dropped fastest when we re-tiered low-priority alerts down to info.
2. Lesson 2: Override-reason iteration. The initial taxonomy had 12 codes. Phase 3 pilot data showed five codes were never selected. We collapsed to 7 codes after pilot. Override-reason data is only tunable when the codes reflect what clinicians actually do.
3. Lesson 3: Prefetch latency budget. End-to-end target under 500 ms (from EHR hook trigger to card render). Production averaged 280 ms with prefetch-only path. Anything above 600 ms and clinicians experienced the card as a workflow stutter; engagement dropped sharply at that threshold. Tune prefetch templates against the EHR sandbox’s typical latency, not against the spec’s theoretical best case.
4. Lesson 4: hookInstance idempotency. A clinician who hits Sign, dismisses the card, and re-Signs triggers a fresh hookInstance. Storing prior hookInstance outcomes and returning consistent card structure on retry prevented the confusing pattern of new wording on second attempt.
5. Lesson 5: Discovery endpoint stability. Update prefetch templates by versioning the service id, not by silently editing prefetch keys. CDS Clients cache the discovery response; silent edits cause stale prefetch and intermittent failures.

A note on what we ship and what we do not. Mindbowser does not have a packaged CDS Hooks accelerator. Our HealthConnect CoPilot accelerator handles the FHIR data layer, which is regulatory-neutral plumbing. The CDS service implementation, the rules engine, the prefetch contract design, the override-reason taxonomy, and the card severity discipline are custom build, modeled on the perioperative-readiness production pattern. There is no shortcut and saying otherwise would oversell what the accelerators do.

For deeper architecture context, the advanced clinical decision support architecture walkthrough covers the rules-engine layer at protocol depth. For the regulatory framing of CDS Hooks-delivered exempt CDS, the FDA clinical decision support regulations piece walks through the Section 3060 fit.

What This Means for Your Build

The CDS Hooks v2.0.1 spec gives you the mechanism. Discovery endpoint, hook lifecycle, request-response shape, JWT auth, CDS Card structure. Read the spec end-to-end before you write a line of code; the whole document is shorter than most teams expect.

What the spec does not give you is the production layer. Prefetch contract latency budget. CDS Card severity tier discipline. Override-reason taxonomy. Card summary writing that fits 140 characters and still communicates clinical reasoning. Feedback-loop integration that tunes the rules engine over time. Those decisions earn the engagement rate.

A team that treats the spec as the floor, ships spec-compliant in month one, and spends the next three months on production tuning will reach 80% or higher provider engagement. A team that treats the spec as the ceiling will hit 30 to 40% and stall.

If you are a senior FHIR developer or CTO scoping a CDS Hooks production build, the engineering pattern is well-documented. We have shipped it. The conceptual primer at the introductory CDS Hooks guide covers the awareness layer for stakeholders who need it.

Request an Assessment. A 30-minute scoping conversation, your CDS Hooks scope plus our production pattern, no obligation. Start a Conversation.