How Integration Health Actually Works

How Integration Health Actually Works

Your customer emails support before your dashboard tells you anything is wrong — that’s the moment this whole pillar exists to prevent. A token expires quietly. A vendor deprecates an endpoint without much warning. A quota runs out at two in the morning. In most integration platforms you find out from the person the failure actually happened to, because the platform holds the credentials and ships no health model at all.

Is my integration broken?

That’s the question, and today most tools can only answer half of it. An outside checker built to watch a URL can tell you it’s unreachable, but to check anything behind a login it asks you to hand over a secret — the exact credential sprawl the rest of this platform exists to avoid. A vendor’s own status page can tell you the platform is up, but it says nothing about your specific connection, your specific quota, or the one integration that depends on both. A silent integration failure sits in the gap between those two answers, and it is the highest-cost failure mode in this category precisely because nobody owns it.

Here, every app declares its own checks as part of its manifest — and a declared check is not the same thing as a host inventing one. When a host has no declared check for a given kind, it reports the target unknown, not okay. It never falls back to picking some arbitrary read action and hoping the answer means something, the way an undeclared probe would. See the Health Check spec for the full shape of what an app is allowed to declare.

What actually counts as “healthy”?

A single check can answer more than one question, so the model separates what the answer is about from what it tells you. A check has a declared kind — is the vendor’s platform up, is this stored credential live, is there quota headroom, is a dependency you own reachable — and a declared scope, so a vendor-status check runs once and is shared across every connection instead of hammering a status page once per customer.

That separation is also what lets one probe report several components at once. A vendor’s own status API can say the core platform is fine while webhooks are degraded, and a single boolean would erase exactly that distinction — usually the one a support ticket is actually about. A health check here can carry a components map for that shape, rolled up into one worst-state verdict, so a status page can say not just “broken” but which part, attributed back to the specific check that produced it.

Whose API is it, anyway?

Your own APIs sit in the same view, not a second dashboard bolted on next to the vendor one. Register your service as an app with a dependency check, and first-party and third-party APIs in one view becomes a literal claim rather than a slide — the same object, checked the same way, rolled up through the identical kind/scope/covers model a vendor’s own status check uses. And because a check runs through a connection the platform already holds, watching an authenticated API of your own never means handing anyone a fresh key just to monitor it.

Shipped today: the spec, the reference runtime, status-feed parsing for vendors who publish one, per-check egress so a status probe reaches only the host it needs, on-demand checks over the API, live status in Studio, and declared probes across the first-party app catalog. Not yet: recurring monitors that poll on a schedule, assertions against a health target, alerting on a state change, and history — the roadmap half of this pillar, named as roadmap rather than dressed up as shipped.

Who finds out first?

Ask yourself who finds out first when an integration breaks — you, or the person paying you. That’s not rhetorical; it’s the actual dividing line between a platform that ships a health model and one that ships a catalog of connectors and treats a broken integration as somebody else’s problem. A check that travels with the app — declared once by whoever built the integration, not invented later by a host guessing — is what makes “is my integration broken” answerable before it’s a support ticket instead of after.