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

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

CDS Hooks

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

The product team wanted a SMART on FHIR app—great, I’ve done that before.
But then they the documentation they gave me leaned towards custom Practice Advisories, which I had not built before.

“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 seemed like I had a glimpse into the future of what hl7v2 could be—triggering alerts and decision support automatically, based on provider actions.

Eager to dive in headfirst, I quickly learned that CDS Hooks is both incredible and uniquely painful.

Here are 10 things I wish I knew before getting too far.

1️⃣ Different from SMART on FHIR

I came in expecting CDS Hooks to be an extension of SMART on FHIR apps—they aren’t.

  • CDS Hooks is event-driven: The EHR calls your service when something happens.
  • SMART apps are user-driven: The provider must manually launch them.

It’s easy to mix them up, but they actually complement each other.
The game-changer? Epic’s August 2024 Launch Cards now allow a CDS Hook to launch a SMART app directly!

👉 CDS Hooks fires before the clinician makes a decision—SMART on FHIR fires when they seek information.

2️⃣ They allow you to generate custom interactive practice advisories

The best feature of CDS Hooks? You can create Practice Advisories—custom pop-ups inside the EHR that provide interactive decision support.

  • You can show alerts, suggest actions, and even pre-fill forms.
  • Unlike basic alerts, these are configurable by the clinician, reducing frustration.
  • They allow custom workflows tailored to different health systems.

Epic already has its built-in Practice Advisories, so you have to integrate carefully to avoid conflicts (more on that later).

3️⃣ Low provider abrasion—your app launches when events of interest happen

One of the biggest advantages of CDS Hooks:
💡 Your app surfaces exactly when it’s needed—without forcing clinicians to search for it.

  • If a provider prescribes a high-risk medication, you can warn them instantly.
  • If a patient meets sepsis criteria, you can suggest interventions in real time.

It’s less annoying than constant alerts and allows passive guidance rather than interruptions.

👉 Good CDS Hooks design = low friction, high impact.

4️⃣ One Epic Instance ≠ Another

“Once you’ve seen one Epic instance, you’ve seen one Epic instance.”

This is especially true for CDS Hooks.

  • Different Epic customers configure Practice Advisories differently.
  • Hook support varies by Epic version and customer settings.
  • Custom scripting can modify how hooks fire.

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

5️⃣ Practice Advisories Can Clash with CDS Hooks

Epic already has built-in Practice Advisories—which means:
🚨 If your CDS Hook isn’t configured carefully, it might overlap with existing alerts.

  • Duplicate warnings = annoyed clinicians.
  • Too many alerts = ignored CDS Hooks.
  • Some Epic customers disable CDS Hooks in favor of their own advisories.

👉 Before implementing CDS Hooks in Epic, understand their existing alerts first.

6️⃣ Most EHR Vendors don’t really support CDS Hooks (yet)

HTI-2 is mandating support by 2028, but adoption is still low.
👉 Check your target EHR’s actual support before committing to CDS Hooks.

7️⃣ EHR Vendors Don’t Leverage Service Discovery at All 😞

In a perfect world, CDS Hooks services should be dynamically discoverable—just like a FHIR server.

👉 If you’re planning for service discovery, don’t.

8️⃣ Expect to Pay $380/hr for Epic Testing

Epic’s vendor services sandbox environment is quite limited for full CDS Hooks testing.

Problems with Epic's vendor services sandbox:

  • One card at a time, doesn't support multiple cards
  • Can't configure look and feel
  • Can't test interactivity such as suggestions/actions

To properly test:
✅ You need to pay $380/hour for Epic Vendor Services (VS) testing.

👉 Budget for testing early. It’s not free, but it's a good experience and the calls are productive.

9️⃣ Write-Back Calls Are First-Class in Epic, But Nobody Uses Them

Did you know that CDS Hooks can actually write data back into the EHR?

No need for extra steps to get conditions onto the problem list, today's encounters, or even medications.

🔟 Launch Cards (August 2024)

Before August 2024, a CDS Hooks card could only display information and provide simple interactivity.

🚀 Now, with Epic’s Launch Cards, a CDS Hook can launch a full SMART on FHIR app inside the EHR!

This is huge because:

  • You can seamlessly transition from a CDS Hook alert to a full app.
  • Clinicians don’t have to search for external tools—they launch automatically.
  • It bridges the gap between event-driven alerts and full interactive workflows.

🎯 Final Thoughts

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

✅ Budget for testing upfront.
✅ Avoid assuming EHR implementations are consistent.
✅ Push for vendor improvements (especially service discovery).

CDS Hooks is powerful, but it’s still early even though it's been around.
If you’re getting into it now, hopefully, these lessons save you some pain.

Who's ready to tackle social determinants of health with CDS Hooks?

👉 What lessons have you learned with CDS Hooks?
📌 Hopefully more support will follow - HTI-2 comment.