How to Turn Vendor Status API Responses into Consistent Alerts

Identify what the API actually promises

A vendor may return current component health, open incidents or a historical event feed. Check which contract applies before interpreting the payload. A component missing from an active-incident list can mean recovery; a component missing from a partial page of results means only that the page was incomplete.

Record pagination, rate limits, timestamps, authentication scope and the meaning of each status value. For an internal adapter, explicitly map every known value and send newly introduced values to an unknown state until reviewed.

Avoid deriving identity from display names. A renamed component should update its description, not silently create a second incident while the original remains open.

Define a transition table

Use one durable key per tenant, source, component and monitored condition. Store the last valid source observation alongside the adapter's receipt time.

This is a proposed adapter contract, not universal vendor behavior. Some sources have multiple degraded states; retain those distinctions if they change urgency or action.

Make retries safe

Persist a transition before marking it delivered, and record its delivery outcome. Give the downstream API a stable incident or deduplication key where supported. If the downstream integration cannot provide idempotency, implement a reconciliation step and document the remaining duplicate risk.

Do not equate a successful HTTP response with human delivery. Record transport acceptance separately from the incident appearing in the destination. A recovery update should refer to the same key as the opening event.

After an adapter restart, load the saved state before polling. Otherwise every currently unhealthy component may look like a new incident. Define what to do on the first observation when no prior state exists: create an explicitly current-state incident, or stage it for review, according to the service's urgency.

Handle freshness independently

Expose last successful poll time, response validation errors and delivery backlog. A vendor service may remain unhealthy while its status API also becomes unavailable. Preserve both facts instead of replacing the incident with a reassuring green state.

If a dashboard presents this information, label stale observations and show their age. Grafana's No Data and Error documentation (opens in a new tab) illustrates why empty results and failed evaluation need explicit treatment; your adapter needs its own equivalent contract.

Replay an entire incident before enabling pages

Use fixture responses that progress through healthy, unhealthy, repeated unhealthy, fetch failure and recovery. Repeat the exercise across a process restart. Include a duplicate delivery, a late unhealthy observation after recovery, and a newly added component.

Check that one incident remains associated with its original identity, recovery occurs only on qualifying evidence and adapter failures reach an owner. Compare observed timestamps with received timestamps so delayed data cannot move the timeline backwards unnoticed.

Start with a review destination. Once the transition record explains every opening, update and recovery, connect the production route and retain the fixtures as regression checks. The MSP consolidation guide covers how this adapter fits into a shared event pipeline.