CDS Hooks in Practice: Building Real-Time Clinical Alerts

What Are CDS Hooks?

CDS Hooks is a standard for invoking external Clinical Decision Support (CDS) services from within an EHR workflow. When a clinician performs a specific action — opening a patient chart, entering an order — the EHR sends a JSON request to your CDS service, and you respond with cards, suggestions, or links.

Discovery Endpoint

Your CDS service must expose GET /cds-services listing the hooks it supports:

{
  "services": [{
    "hook": "order-select",
    "id": "drug-interaction-check",
    "title": "Drug Interaction Checker",
    "description": "Checks for interactions between the ordered drug and the patient's active medications.",
    "prefetch": {
      "patient": "Patient/{{context.patientId}}",
      "medications": "MedicationRequest?patient={{context.patientId}}&status=active"
    }
  }]
}

Handling a Hook Request

When the hook fires, the EHR sends a POST with the hook name, context, and any prefetched FHIR resources. Your service processes the request and returns cards:

@PostMapping("/cds-services/drug-interaction-check")
public CdsResponse handle(@RequestBody CdsRequest request) {
    List<MedicationRequest> existing = request.prefetch("medications");
    MedicationRequest ordered = request.context("draftOrders").get(0);

    List<String> interactions = interactionChecker.check(ordered, existing);
    if (interactions.isEmpty()) return CdsResponse.empty();

    return CdsResponse.of(Card.builder()
        .summary("Potential drug interaction detected")
        .detail(String.join("
", interactions))
        .indicator(Indicator.WARNING)
        .source(Source.of("Akhester CDS", "https://ajfhir.com"))
        .build());
}

Card Types

CDS cards come in three indicator levels: info (blue), warning (yellow), and critical (red). Cards can include suggestions (proposed actions the clinician can accept with one click) and links to external resources.

SMART on FHIR Context

If your CDS service needs to call back into the EHR's FHIR API, the hook request includes a fhirAuthorization object with an access token. Use it as a Bearer token on FHIR API calls — it is scoped to the current patient and expires after the session.

Testing in Epic Sandbox

Epic's sandbox supports CDS Hooks testing via the Developer App Activation tool. Register your /cds-services discovery URL, select the hook, and trigger it from within the sandbox EHR. Epic validates the response shape strictly — ensure your cards conform to the CDS Hooks specification exactly.

Have questions about implementing this in your healthcare platform? Get in touch with the Akhester team.