CDS Hooks: What Nobody Tells You Before You Build

Six months ago, I thought CDS Hooks would be straightforward. Pop up some alerts in Epic, help doctors make better decisions, ship it.

I was spectacularly wrong.

The product team wanted us to "wow Epic customers with the art of the possible." What we discovered was that the possible came with a lot of fine print.

1. It's Nothing Like SMART on FHIR

First mistake: thinking CDS Hooks would work like SMART apps. Nope.

SMART apps sit there waiting for someone to click a button. CDS Hooks jump out at you when the EHR thinks you need them. One waits to be asked, the other interrupts your workflow.

The mental model shift took me weeks to grasp. You're not building an app anymore. You're building a backseat driver for the EHR.

(Side note: Epic finally let CDS Hooks launch SMART apps in August 2024. Game changer if you can use it.)

2. Practice Advisories Are Your Actual Product

Forget everything you know about UI design. In CDS Hooks land, you get a card. That's it.

Want a button? Here's your card. Need a form? Card. Complex workflow? Still a card.

The art is cramming everything useful into that tiny rectangle without making doctors want to throw their computers out the window.

3. Timing Is Everything (And You Don't Control It)

The promise: Your alert appears exactly when the doctor needs it. The reality: Your alert appears when the EHR feels like firing the hook.

Sometimes that's perfect. Doctor opens the med list, sees your drug interaction warning, avoids a problem. Beautiful.

Other times? Your sepsis alert fires while they're documenting a flu shot. Not so beautiful.

4. Every Epic Instance Is a Special Snowflake

Built your CDS Hook for Hospital A? Congrats, it's broken at Hospital B.

Hospital A configured their advisories one way. Hospital B did something completely different. Hospital C? They wrote custom scripts that break everything.

I learned this the hard way when our "working" integration failed spectacularly at three different sites. Same Epic version. Completely different behaviors.

5. You're Fighting Epic's Own Alerts

Epic has alerts. Lots of them. Yours is just another voice in the choir.

We once deployed a medication warning that fired alongside Epic's own medication warning. Same message, different format. Doctors got both. They were... not pleased.

The worst part? Some hospitals turn off CDS Hooks entirely because they trust Epic's advisories more than yours. Can't blame them.

6. Nobody Actually Supports This Yet

HTI-2 says everyone needs CDS Hooks by 2028. Cool story.

Right now? Epic sort of supports it. Cerner might. Others? Good luck.

We spent three months building for "industry standard" CDS Hooks only to discover our target hospitals couldn't actually run them.

7. Service Discovery Is a Lie

The spec has this beautiful service discovery mechanism. Your CDS service announces what it can do, the EHR automatically configures everything. Magic.

Reality: You manually configure each hook at each site. With spreadsheets. And emails. So many emails.

8. Testing Costs Real Money

Want to test in Epic's sandbox? That'll be $380/hour, minimum four-hour blocks.

Oh, and the sandbox only shows one card at a time. Need to test multiple alerts? Too bad. Want to see how it actually looks? Not happening. Interactive features? Forget it.

We burned through $15,000 in testing before we got something that worked in production. Budget accordingly.

9. The Write-Back Feature Nobody Uses

Here's a secret: CDS Hooks can write data back to the EHR. Add problems to the problem list. Update medications. Document findings.

Nobody uses this. Why? Because if you screw up and write bad data, you're liable. We looked at it, ran the numbers on malpractice insurance, and noped right out.

10. Launch Cards Changed Everything (But Only in Epic)

August 2024: Epic finally let CDS Hooks launch SMART apps. This is huge.

Before: Your card shows a warning. Doctor has to close it, find your app, launch it, do the thing. After: Your card shows a warning with a button. Click. App opens. Done.

It only took them years to implement what should have been obvious from day one.

Would I Do It Again?

Yeah, probably. But differently.

CDS Hooks can genuinely help doctors make better decisions. When it works, it's magic. A subtle nudge at exactly the right moment can prevent real harm.

But go in with your eyes open. Budget double what you think. Test at three different Epic sites minimum. And for the love of all that is holy, check what alerts they already have before you add yours.

The future is event-driven clinical decision support. We're just living through the messy part where nobody agrees how it should work.

Welcome to the bleeding edge. It's sharp here.