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.
This diagram makes it look so simple
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 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.
Related Articles
Your Support Team Is Claude Code on a Timer
An L2 support engineer that's just Claude Code on a /loop, with all its state living in Slack reactions. No app, no database, no deploy — and it only pings you when it's real.
What an AI Audit Actually Finds
Most teams asking for AI don't have a model problem. They have a "which problem is even worth it" problem. Here's what a real AI audit surfaces — and why "don't build this" is often the most valuable line in the report.
Inside a Production Voice Agent: How the Stack Actually Ships
Production voice-AI has converged on a pattern: graph-based conversations, separated decision and response prompts, synthetic-call regression testing, and per-component latency budgets. Why the stack looks the way it does — and what most teams are still missing.
Building something like this?
I help teams ship AI in production — audits, consulting, custom agents, and eval systems. Start with an AI Audit (from $5k) for an honest read on what to build.