10 Things I Wish I Knew Before Building a CDS Hooks-Enabled FHIR Application

The Journey Begins

A while back, I was showing off some FHIR capabilities with a pre-visit chart review tool I had built. It sparked genuine interest and led to me spearheading a FHIR application to help close gaps in value-based care operations.

The product team initially wanted a SMART on FHIR app—great, I'd done that before.
But then they handed me documentation that leaned heavily toward custom Practice Advisories, which was new territory for me.

"We want to wow our Epic customers by showing them the art of the possible."

That's when CDS Hooks-enabled Practice Advisories entered the picture. It felt like I had glimpsed the future of healthcare interoperability—triggering alerts and decision support automatically, based on provider actions.

Eager to dive in, I quickly discovered that CDS Hooks is both incredibly powerful and uniquely challenging.

10 Things I Wish I Had Known Before Starting

1. CDS Hooks Is Fundamentally Different from SMART on FHIR

I initially expected CDS Hooks to be an extension of SMART on FHIR apps—they're not.

CDS Hooks	SMART on FHIR
Event-driven: The EHR calls your service when something happens	User-driven: The provider must manually launch them
Proactive	Reactive
Fires before decisions are made	Launches when information is sought

While easy to confuse, they actually complement each other beautifully. The game-changer? Epic's August 2024 Launch Cards now allow a CDS Hook to launch a SMART app directly!

2. Create Interactive Practice Advisories That Actually Help

The most powerful feature of CDS Hooks is the ability to create Practice Advisories—custom pop-ups inside the EHR that provide interactive decision support:

• Show contextual alerts with actionable information
• Suggest specific actions and pre-fill forms
• Allow clinician configuration, reducing alert fatigue
• Enable custom workflows tailored to different health systems

Epic already has built-in Practice Advisories, so integration requires careful planning to avoid conflicts.

3. Achieve Low Provider Friction with Contextual Awareness

One of the biggest advantages of CDS Hooks:

Your app surfaces exactly when it's needed—without forcing clinicians to search for it.

This contextual awareness enables powerful use cases:

• Warning providers about high-risk medication interactions at the point of prescribing
• Suggesting interventions when a patient meets sepsis criteria in real time
• Offering relevant clinical recommendations based on lab values as they're reviewed

It's significantly less disruptive than constant alerts and enables passive guidance rather than frequent interruptions.

Good CDS Hooks design = low friction, high impact.

4. Epic Instance Variability Is a Major Challenge

The healthcare IT community has a saying:

"Once you've seen one Epic instance, you've seen one Epic instance."

This variability is especially pronounced with CDS Hooks:

• Each Epic customer configures Practice Advisories differently
• Hook support varies by Epic version and customer-specific settings
• Custom scripting can fundamentally alter how hooks fire in production

If you build for one Epic system, don't assume it will work identically for another.

5. Navigating Potential Conflicts with Existing Advisories

Epic's built-in Practice Advisories can clash with your CDS Hooks implementation:

🚨 If your CDS Hook isn't configured carefully, it will overlap with existing alerts.

The consequences can be significant:

• Duplicate warnings lead to frustrated clinicians
• Too many alerts result in ignored CDS Hooks (alert fatigue)
• Some Epic customers disable CDS Hooks entirely in favor of their own advisories

Before implementing CDS Hooks in Epic, thoroughly analyze their existing alert ecosystem.

6. Limited EHR Vendor Support (For Now)

While HTI-2 is mandating support by 2028, current adoption remains relatively low.

7. The Service Discovery Dream Remains Unrealized

In an ideal world, CDS Hooks services would be dynamically discoverable—just like a FHIR server.

Unfortunately, EHR vendors don't currently leverage service discovery capabilities, making implementation more manual and cumbersome than the specification suggests.

If you're planning for automatic service discovery, adjust your expectations.

8. Budget for Thorough Testing

Epic's vendor services sandbox environment has significant limitations for CDS Hooks testing:

Limitation	Impact
One card at a time	Can't test multiple concurrent advisories
Limited configuration options	Can't test look and feel customizations
No interactive testing	Can't test suggestion/action workflows

For comprehensive testing, you'll need to budget approximately $380/hour for Epic Vendor Services (VS) testing time.

While expensive, these testing sessions deliver valuable insights and are worth the investment.

9. Underutilized Write-Back Capabilities

CDS Hooks can actually write data directly back into the EHR—a powerful feature that remains largely untapped.

This capability eliminates extra steps for documenting:

• Problems on the problem list
• Findings in today's encounters
• Medications in the medication list

10. Launch Cards: The Integration Breakthrough (August 2024)

Prior to August 2024, CDS Hooks cards could only display information with limited interactivity.

This breakthrough enables:

• Seamless transitions from alerts to full applications
• Automatic tool launching without manual intervention
• A bridge between event-driven alerts and comprehensive interactive workflows

Moving Forward with CDS Hooks

Would I build a CDS Hooks app again? Yes—but with recalibrated expectations.

For successful implementation:

• ✅ Budget adequately for testing from the beginning
• ✅ Approach each EHR instance as unique
• ✅ Advocate for vendor improvements, especially around service discovery

CDS Hooks represents a powerful paradigm in healthcare IT, but it's still maturing despite being around for years. If you're implementing it today, these insights should help you navigate the challenges more effectively.

What's Next?

Who's ready to tackle social determinants of health with CDS Hooks? The possibilities for improving care coordination through contextual awareness are tremendous.

What lessons have you learned implementing CDS Hooks?
Join the conversation about HTI-2 requirements