Connector health and silent failure
An integration that quietly stopped syncing three weeks ago is an incident. What the platform checks, what it records, and why you still have to look.
An integration that stopped working three weeks ago and said nothing is not a cosmetic problem. It is a gap in your coverage that has been open for three weeks, and it looks exactly like an integration that is working. This article is about how to tell the difference, and it is honest about how much of that work is currently yours.
The failure mode that matters is not 'the admin pressed Test and it went red', it is 'nobody pressed Test for three weeks and the directory sync had stopped on day two'. A silent integration is indistinguishable from a working one until somebody looks, so something has to look.
What the platform does on its own
A loop in the background worker re-probes every configured integration whose last check is older than 15 minutes. It works in batches of 50, runs up to 8 checks at once, and gives each individual check 20 seconds. Separately, it looks ahead 21 days for credentials that are about to expire.
Each probe records one of four states against the integration, and the distinction between two of them is the useful part:
- healthy
- The provider answered and accepted our credentials.
- degraded
- The provider answered and refused us — usually an expired or revoked token. This is deliberately not reported as unreachable: the service answered, it just said no. The distinction is what tells you whether to rotate a credential or wait for somebody else's outage to pass.
- unreachable
- We could not get an answer at all.
- disabled
- The integration exists but is switched off, or has no configuration. An unconfigured notification target reports this with the message
connector is not configured.
One related design decision is worth knowing, because it is the difference between a useful timestamp and a misleading one: a failed sync does not advance the last-sync time. A failure leaves the previous successful timestamp where it was and records the error separately. A failed sync that stamped a success time is precisely how an integration stops working without anybody noticing.
What you can see, and where
Every integration in the list carries four derived fields answering the question the whole surface exists for — is anything quietly broken?
needs_attention— a single boolean. The list response also carries a count of how many of your integrations have it set, which is the one number to look at.attention_reason— one sentence you can act on. The exact wordings are below.sync_is_stale— true when an enabled integration that is supposed to sync has not done so for 48 hours. Sign-on and notification destinations are event-driven and are never marked stale, because there is no sync to be stale.connector_status— the catalogue maturity, so an integration you configured from a beta row stays labelled beta afterwards.
the upstream service is unreachable: <the provider's message>
the connection authenticates but is not fully working: <the provider's message>
the stored credential expired on 2026-08-14T09:00:00Z
the stored credential expires on 2026-09-12T09:00:00Z
this integration has never completed a sync
no successful sync since 2026-08-09T02:15:00Z
last operation failed: <the error>For one integration, GET .../instances/{instanceID}/health returns its current state plus its recorded history — the last 100 events by default, up to 500. That history is how you find out that an integration has been flapping rather than cleanly broken, which usually points at a rate limit or an intermittent network path rather than a bad credential.
What it does not do: tell you
Two smaller gaps belong alongside that one, because they change what the health list means.
- Template-driven instances are never probed. Single sign-on applications and inbound provisioning targets have no connector to health-check, so the runner skips them and their health is inferred from their last successful use instead. A sign-on application that nobody has used for a month is not reported as broken — nor as working.
- If credential encryption is unavailable at startup, the health runner does not start at all. It cannot open your stored tokens to test them, so it stops rather than reporting everything as healthy. That is the right choice, but the visible effect from your side is a health list that never updates, not an error.
The manual check to run, and how often
Once a week, and after any change to a credential at the provider's end. It takes about a minute.
Open the integrations list and read one number
The
needs_attentioncount. If it is zero, you are done. It is derived from live state — health status, last error, sync staleness and credential expiry — rather than from anything anyone remembered to update.For anything flagged, read the reason before touching it
The seven sentences above map to genuinely different actions. Degraded almost always means a credential to rotate. Unreachable usually means waiting, or a firewall change at their end. No successful sync since a date means the sync is failing rather than the connection, and the last error will say why.
Run a connection test
Testing an existing integration re-probes it now rather than waiting for the next 15-minute pass, and gives you a plain-language result. Remember what a green test proves and does not: see Configuring a connector. Testing needs write permission, not read.
For a directory connector, check the sync separately
Health and sync are two different questions. A connector can authenticate perfectly and still not be syncing. Run a sync with the dry-run option first — it returns what would change, capped at 200 users, without changing anything — so you can see whether the data is what you expect before you let it write.
Put a calendar reminder on credential expiry
Until the expiry warning reaches somebody, the stored expiry date is only useful if a person looks at it. When you create an integration with a credential that expires, write the date in your own calendar with a fortnight's notice. This is a workaround for a gap on our side and we are not pretending otherwise.
What to do next
- Configuring a connector — rotating a credential without deleting and recreating the integration.
- Where notifications go — what the platform does tell you about, and what it does not.
- How to get help — if an integration is degraded and the reason does not match anything above, send us the instance identifier.