Detect breaking API changes in production

Third-party APIs drift without warning. If your integration logic assumes yesterday's payload shape, today's upstream rollout can become your production incident.

This guide shows how to monitor API contracts as operational dependencies, keep diffs deterministic, and route incidents to the right owner before customer flows break.

What counts as breaking drift

Treat these as contract-risk events:

• Removed field used by mapping or business logic.
• Renamed field with no backwards-compatible alias.
• Type change (string to object, number to string).
• Requiredness change (nullable to required, optional to required).
• Nested shape change in arrays/objects consumed by downstream code.

A simple rule: if your parser, validator, or transform would fail or silently mis-handle data, treat it as breaking drift.

Stabilize signal (select + ignore + canonicalization)

High-signal monitoring starts with selecting only contract-critical JSON paths and ignoring volatile metadata.

{
  "selectJsonPaths": [
    "data.customer.id",
    "data.customer.status",
    "data.subscription.plan",
    "errors[*].code"
  ],
  "ignoreJsonPaths": [
    "meta.requestId",
    "meta.traceId",
    "meta.generatedAt"
  ]
}

Then canonicalize before diffing/hashing so field order and non-semantic formatting do not create false positives. Deterministic input gives deterministic diffs.

Triage workflow (incident lifecycle)

When meaningful drift is detected:

1. Incident opens automatically with structured diff context.
2. On-call or service owner acknowledges to claim triage.
3. Resolve if drift is unexpected and remediated.
4. Accept baseline when rollout is expected and now represents the new contract.

Baseline acceptance should be an explicit operational decision, not an accidental side effect of "latest snapshot wins".

Automation and idempotency mindset

Route diff.detected events to incident tooling and chatops using webhooks. Treat webhook consumers as idempotent by keying on event identity/fingerprint.

const event = {
  schemaVersion: 'v1',
  eventType: 'diff.detected',
  eventId: 'evt_01JX...',
  occurredAt: '2026-02-11T12:41:00.000Z',
  monitorId: 'mon_123',
  data: {
    diff_fingerprint: 'sha256:abc...',
    diff_summary: { added: 1, removed: 0, changed: 2 },
    changes: [/* structured change records */],
    links: { monitor: '...', diff: '...' },
  },
};

Use request IDs and delivery logs to correlate downstream processing failures and retries.

Start here

• API change monitoring: product path for JSON/API contract drift.
• Website change detection: pair API monitors with DOM/metadata contract checks.
• Pricing: choose interval and delivery options for your incident workflow.

Next steps

• Define Tier 1 API dependencies and assign response owners.
• Create one monitor per external contract boundary, not per endpoint variant.
• Start with narrow selectJsonPaths, then expand only when needed.
• Wire webhooks into your incident system before increasing check frequency.

Related guides

• Monitor third-party dependencies
• Change detection vs visual regression testing
• Website change detection guide

Start monitoring with DiffMon

Use API change monitoring to deploy your first contract monitor, expand into website change detection for HTML/DOM drift, then pick the right operational cadence on pricing.