Connection health

Some failures are predictable. A provider tells you on every response how much of your allowance is left. A credential has an expiry date. A signing secret that was rotated on one side fails every check from that moment. Connection health reads these and warns before, or at the moment, they turn into errors.

Seamward stores numbers, booleans and dates for all of this. It never stores a header, a signature, a signing secret, a token or a certificate.

Rate-limit headroom

The collector reads the provider's rate-limit headers on your outbound calls and sends three whole numbers: the limit, what remains, and the seconds until it resets. The envelope reference lists the headers and formats.

quota-headroom-low is raised when, for one advertised limit, the lowest remainder was under 15% of the limit in at least three separate hours of the last 24. An hour counts only if it has at least five calls. One low reading is a busy minute; several low hours in a day is an allowance about to run out.

A provider that advertises different limits for different endpoints is judged per limit.

A changed limit

quota-limit-changed is raised when a limit advertised over the previous day stops being advertised and exactly one new limit takes its place in the last hour, each seen on at least five calls. The summary says whether it was lowered or raised, and from what to what. It is raised once per change.

If several limits move at once there is no honest pairing to report, and nothing is raised.

Signature checks

Seamward does not verify signatures and never sees one. Your webhook handler already does, so it reports the result as a boolean: see reporting a signature result.

signature-failure-shift is raised when the share of failed checks in the last 15 minutes is at least 20 percentage points above the previous day's, over at least ten checked deliveries. It separates a rotated signing secret from a general error spike: without it, both look like a rise in 401 responses.

A connection that reports no signature results raises nothing.

Credential expiry

On a connection's Overview, the Connection health card has a Credential expiry section. Owners and admins record:

There is no field for the credential itself. An unknown field is refused, and so is a name that looks like a key (a long unbroken run of key characters). A connection holds up to 20 entries.

Inside the warning period an advisory opens with the date. It is marked Within 30 days when seven days or fewer remain, and Date passed after it. Change the date after a renewal and the advisory is withdrawn until the new date comes round. An alert destination subscribed to advisory.opened is told when it opens and again at seven days.

Where it shows

• The Connection health card on a connection: the lowest headroom of the last day against the limit, how many signature checks failed, and each recorded date with its countdown.
• Detected changes on the connection lists the three findings.
• Advisories lists credential expiry beside provider notices.
• Through MCP, get_integration returns the dates your team recorded and list_advisories returns the advisories.
• From the CLI, seamward connections health ID returns the dates and both meters as JSON.

Boundaries

• Findings here do not open incidents. They are warnings on the connection. A 401 spike that follows still raises its own finding.
• A meter is the provider's claim. Seamward reports the numbers the provider sent.
• Traces carry none of this. A connection fed only by OpenTelemetry traces has no rate-limit numbers or signature results.

Next steps

• Collector reference: where headers are read and how to return a signature result.
• Advisories: how a dated warning is decided on.
• Alerts: send them to your team.