Catch breaking API changes

External APIs and webhooks can stay online while changing a field, type, or response pattern your application depends on. Uptime checks see a healthy endpoint; your integration sees a broken contract. This page walks one incident end to end so you can see exactly what Seamward gives you when it happens.

The scenario

Your hiring platform consumes candidate webhooks from an ATS provider. For months, every event has looked like this:

{  "candidate": {    "id": "cand_812",    "email": "ada@example.com",    "salary": "85000"  }}

On a Tuesday, without a changelog entry, the provider starts sending salary as a number instead of a string. Your parser expects a string, the mapping silently produces NaN, and compensation data stops syncing. No 500s, no provider outage, no alert from transport monitoring: every webhook is still acknowledged with a 202.

What changed, as data

Seamward never sees the salary values. The collector derives each payload's structural shape inside your process, and the shapes are what changed:

{  "kind": "object",  "fields": {    "candidate": {      "kind": "object",      "fields": {        "email": { "kind": "string" },        "id": { "kind": "string" },        "salary": { "kind": "string" }      }    }  }}

{  "kind": "object",  "fields": {    "candidate": {      "kind": "object",      "fields": {        "email": { "kind": "string" },        "id": { "kind": "string" },        "salary": { "kind": "number" }      }    }  }}

Two different shapes produce two different fingerprints, and a new fingerprint appearing against an established baseline is exactly what drift detection compares.

What Seamward shows you

Within seconds of the first changed webhook, the integration carries a finding with the exact path:

{  "kind": "type-changed",  "path": "$.candidate.salary",  "expected": "string",  "observed": "number"}

Related findings group into an incident with first and latest occurrence, the affected observation count, and the release context of the code that processed the traffic. That last part answers the question that usually burns an hour: did the provider change, or did we deploy something? If the shape changed while release: 2026.08.12 was serving steadily, it was the provider; if it changed two minutes after 2026.08.15 shipped, look at your own diff first.

The instrumentation

Everything above comes from one wrapper around the handler you already have:

const handleCandidateWebhook = seamward.observeWebhook(  {    routeTemplate: "/webhooks/candidates",  },  existingCandidateHandler,);

No declared schema is required: the baseline is established from observed evidence. If you register OpenAPI for multiple operations, or JSON Schema for this webhook operation, detection gets stricter because required fields become explicit and a field-removed finding fires when one disappears. Seamward matches the observation to its operation before choosing the schema.

Review findings

A finding is evidence that something changed, not proof of customer impact. The review that turns it into a decision:

1. Confirm the affected integration, environment, and operation.
2. Compare the previous and observed structure at the reported path.
3. Check the first occurrence against your release history.
4. Check whether the same observations also produced errors or missing expected outcomes.

From a confirmed incident, the repair workflow takes over: replay-validated proposals, recorded approval, and delivery.

Operating boundaries

• Seamward does not sit between the provider and your application; collection happens after your handler runs.
• Collection failure never replaces your application's result or the provider acknowledgement.
• Raw payload values are not needed, stored, or compared: structure only.
• An engineer confirms business impact before any repair or provider escalation.

Related: Contracts and operations for registration and matching, Drift detection for baselines and finding kinds, and Redaction for exactly what leaves your process.