CDS Hooks and FHIR for Drug Interaction Alerts: Implementation Guide

Clinical Decision Support (CDS) in electronic health records has traditionally been implemented through proprietary integrations tightly coupled to specific EHR platforms. A drug interaction alert built for Epic works differently than one built for Cerner, which works differently than one built for MEDITECH. This fragmentation means that drug interaction knowledge services must be rebuilt or adapted for each EHR deployment, multiplying development cost and slowing adoption of improved interaction detection.

CDS Hooks is an HL7 standard that addresses this problem by defining a lightweight, HTTP-based protocol for triggering clinical decision support from within EHR workflows. Instead of embedding CDS logic inside the EHR, CDS Hooks allows external services to respond to defined clinical events (called hooks) with cards that display actionable information to clinicians. The EHR calls out to the CDS service at specific workflow points, and the service returns cards that the EHR renders in its native UI.

For drug interaction checking, this architecture is transformative. A single CDS Hook service backed by a drug interaction API can serve interaction alerts to any EHR that supports the CDS Hooks specification, without requiring platform-specific integration code. The interaction knowledge, severity scoring, and evidence citations live in the external service, and the EHR handles only the presentation and user interaction.

The CDS Hooks protocol involves three roles: the EHR (the client that triggers hooks), the CDS Service (the external service that responds with decision support), and the FHIR Server (the data source the CDS Service queries for patient context). In practice, the EHR often embeds the FHIR server, so the CDS Service receives patient data either as prefetch data included in the hook request or by querying the EHR's FHIR endpoint.

The interaction flow follows a simple request-response pattern. The EHR encounters a defined hook point in the clinical workflow, such as a clinician signing a medication order. The EHR sends an HTTP POST to the CDS Service's endpoint with context data including the patient identifier and the medications involved. The CDS Service evaluates the data, checks for interactions, and returns a set of cards describing any findings. The EHR renders these cards in its interface.

Each card has a summary (short text shown as the card title), a detail field (longer explanation), an indicator (info, warning, or critical that determines visual presentation), a source (attribution for the information), and optional suggestions (actions the clinician can take, such as modifying the order). This structure maps naturally to drug interaction alerts where the summary identifies the interacting pair, the detail describes the mechanism and risk, the indicator maps to severity level, and suggestions can include dose adjustments or alternative medications.

CDS Hooks defines several standard hook points, and two are particularly relevant for drug interaction alerting: order-sign and order-select.

The order-sign hook fires when a clinician is ready to sign (finalize) a medication order. At this point, the complete order details are available including the medication, dose, route, and frequency. This is the most common hook point for drug interaction checking because it catches interactions before the order is committed, and the full medication context is available for evaluation.

The order-select hook fires earlier in the ordering workflow, when a clinician selects a medication but before entering dosing details. This hook point enables earlier alerting, potentially steering the clinician away from a problematic medication before they invest time in dosing configuration. However, the trade-off is that dose-dependent interactions cannot be evaluated at this stage because dosing has not been specified yet.

The HL7 PDDI-CDS Implementation Guide recommends supporting both hook points with differentiated behavior. Use order-select for contraindicated and major interactions that are dose-independent, providing early warning for combinations that should be avoided regardless of dose. Use order-sign for the full range of interactions including dose-dependent moderate interactions that require complete order context to evaluate.

HL7 has published a FHIR Implementation Guide specifically for Potential Drug-Drug Interaction (PDDI) Clinical Decision Support. This IG provides detailed guidance on how to structure CDS Hook requests and responses for drug interaction alerting, including data models, value sets, and recommended behavior patterns.

The PDDI-CDS IG defines a structured approach to interaction alerting that goes beyond simple pair detection. It specifies how to represent the contextual factors that influence interaction significance, such as patient age, renal function, and concurrent laboratory values. It also defines how to communicate the evidence basis for each interaction alert, linking to specific FDA label sections or clinical guideline references.

One important concept from the PDDI-CDS IG is the distinction between non-serious and serious potential drug-drug interactions. The IG recommends that non-serious PDDIs be communicated as information cards (indicator: info) that do not interrupt workflow, while serious PDDIs use warning or critical indicators. This aligns with the severity-based alert tiering that RxLabelGuard supports through its severity classification system.

The IG also addresses the filter mechanism, allowing the EHR to specify what types of interactions it wants to receive. An EHR might configure the CDS Service to return only serious interactions to reduce alert volume, or to include all interactions for a comprehensive view. This configuration happens through the CDS Hooks prefetch template and service registration.

A CDS Hook service for drug interaction checking is fundamentally a web service that accepts hook requests, extracts medication information, checks for interactions, and formats the results as CDS Hooks cards. RxLabelGuard can serve as the knowledge backend for this service, handling the drug resolution, interaction detection, and severity scoring while your service handles the CDS Hooks protocol layer.

The service needs to implement three endpoints. A discovery endpoint (GET /.well-known/cds-services) that advertises the available CDS services and their supported hooks. A service endpoint (POST /cds-services/drug-interactions) that accepts hook requests and returns cards. And optionally, a feedback endpoint (POST /cds-services/drug-interactions/feedback) that receives information about how clinicians responded to the cards.

When the service endpoint receives an order-sign hook request, it extracts the medication being ordered from the context.draftOrders field (a FHIR Bundle of MedicationRequest resources) and the patient's current medications from the prefetch data. It then calls the RxLabelGuard API with each new-medication-versus-existing-medication pair. For each interaction found, it constructs a CDS Hooks card with the interaction details mapped to card fields.

The mapping from RxLabelGuard response to CDS Hooks card is straightforward. The interaction's drug pair becomes the card summary. The mechanism, clinical effect, and recommendation become the card detail. The severity level maps to the card indicator: contraindicated and major map to critical, moderate maps to warning, and minor maps to info. The FDA label citation becomes the card source with a link to the DailyMed label page.

CDS Hooks delivers medication context as FHIR resources, so your service needs to parse FHIR MedicationRequest resources to extract drug identifiers. A MedicationRequest includes a medicationCodeableConcept field (or a reference to a Medication resource) that contains coding entries with system and code pairs identifying the medication.

The most useful coding system for drug interaction checking is RxNorm, identified by the system URI http://www.nlm.nih.gov/research/umls/rxnorm. If the MedicationRequest includes an RxNorm coding, you can pass the RxCUI code directly to RxLabelGuard. If the medication is coded in a different system like NDC (http://hl7.org/fhir/sid/ndc), you can either use RxNorm's NDC-to-RxCUI mapping or pass the NDC to RxLabelGuard, which handles the resolution internally.

Prefetch data is a performance optimization in CDS Hooks that allows the EHR to include relevant patient data in the hook request rather than requiring the CDS Service to query the FHIR server separately. For drug interaction checking, the essential prefetch is the patient's active medication list (MedicationRequest or MedicationStatement resources with status=active). Define this in your service discovery response so the EHR includes it automatically.

CDS Hooks supports a feedback mechanism where the EHR reports back to the CDS Service about how clinicians responded to cards. Did the clinician accept the suggestion? Override the alert? Dismiss it without reading? This feedback data is valuable for tuning alert thresholds and measuring the clinical impact of your interaction alerting.

The feedback endpoint receives a JSON payload with the card identifier and the clinician's action (accepted, overridden, or dismissed). Over time, analyzing feedback data reveals which interactions are consistently overridden, suggesting potential alert fatigue issues, and which interactions consistently lead to order modifications, confirming clinical value.

This feedback loop can inform RxLabelGuard's severity classification over time. If a specific interaction classified as major is overridden 95 percent of the time across multiple institutions, that may indicate the severity is too high for the clinical context, or that additional context (like dose thresholds) should be incorporated into the alert logic.

Testing a CDS Hooks service requires a test environment that can simulate EHR hook requests. The CDS Hooks Sandbox (sandbox.cds-hooks.org) provides a web-based testing tool that lets you configure mock patients with medication lists and trigger hook requests against your service endpoint. This is the fastest way to verify your service's protocol compliance and card rendering.

For production deployment, major EHR vendors have their own CDS Hooks integration programs. Epic's App Orchard, Oracle Health's (Cerner) code program, and other platforms each have specific onboarding requirements for CDS Hook services. These typically include security requirements (OAuth 2.0 authentication, HTTPS, audit logging), performance requirements (response time under two seconds), and clinical review of alert content.

The ONC Health IT Certification Program includes criteria for CDS support, and EHRs certified under the 2015 Edition Cures Update are required to support CDS Hooks as part of their standardized API requirements. This regulatory mandate is driving broad adoption of CDS Hooks across the EHR market, making it an increasingly reliable integration target for drug interaction alerting services.

CDS Hooks transforms a drug interaction API from a backend data service into a clinician-facing decision support tool. Without CDS Hooks, a drug interaction API's value is mediated entirely by the consuming application's UI and workflow design. With CDS Hooks, the API's output is rendered directly in the clinician's workflow at the moment of prescribing, exactly when interaction information has the highest clinical impact.

For drug interaction API providers like RxLabelGuard, CDS Hooks compliance means that the API can serve as the knowledge backend for any CDS Hook service, dramatically expanding the addressable market. Instead of requiring each EHR customer to build custom integration code, the interaction data flows through a standard protocol that every major EHR already supports or is required to support.

For development teams evaluating drug interaction APIs, CDS Hooks compatibility should be a key selection criterion. An API that returns structured interaction data with severity levels, evidence citations, and clinical recommendations in a format that maps cleanly to CDS Hooks cards reduces the integration effort from months to weeks.

This information is derived from FDA Structured Product Labeling and is provided for informational purposes only. It should not be used as a substitute for professional medical advice, diagnosis, or treatment. Always consult a qualified healthcare provider.