Stripe Webhooks Breaking in Production? How to Detect Schema Changes Early

What Stripe webhooks look like

Stripe sends webhook events as JSON POST requests to a URL you configure. Each event includes metadata and a nested data.object payload with the actual resource.

I've seen teams spend hours debugging webhook failures that turned out to be a missing field in the payload.

Example endpoint:

https://example.com/webhooks/stripe

Example event payload:

{
  "id": "evt_1Pabc123",
  "object": "event",
  "type": "invoice.payment_failed",
  "created": 1710000000,
  "data": {
    "object": {
      "id": "in_123",
      "amount_due": 5000,
      "currency": "usd",
      "customer": "cus_123",
      "status": "open"
    }
  }
}

A typical webhook handler extracts the nested object and reads fields:

const invoice = event.data.object;
const amount = invoice.amount_due;
const currency = invoice.currency;
const customer = invoice.customer;

How to detect breaking changes in Stripe webhooks

Detecting breaking changes requires comparing payload structures over time. Here's a step-by-step approach:

1. Capture webhook payloads in production — Store or log incoming events so you have a history to analyze.
2. Extract the JSON structure of each payload — Convert each payload into a normalized schema (field paths and types) rather than raw values.
3. Normalize field paths — Use consistent paths like data.object.amount_due so comparisons are reliable.
4. Compare schemas across events — Diff the structure of new events against previously seen schemas for the same event type.
5. Alert when fields are removed or types change — These are typically breaking changes that can cause runtime errors.

In reality, APIs evolve constantly. Doing this manually is tedious; automating it lets you catch changes before they cause production issues.

Why schema changes break integrations

Integration code often assumes specific fields exist and have expected types. Providers don't always announce these changes. When Stripe (or any provider) evolves their API, those assumptions can break. Common scenarios:

• Removed fields — If currency is removed from the payload, code that reads it will fail.
• Type changes — amount_due changing from number to string can break calculations or formatting.
• Nested structure changes — data.object.amount_due moving to data.object.amount.total breaks any code that expects the old path.
• New optional fields — Usually safe, but if a field like discount_amount is added and your code doesn't handle it, you might miss expected behavior. More commonly, added fields are non-breaking.

Example of a breaking webhook change

Suppose your integration receives an invoice webhook. Initially, the payload includes:

{
  "data": {
    "object": {
      "amount_due": 5000,
      "currency": "usd"
    }
  }
}

Later, Stripe changes the payload and removes currency:

{
  "data": {
    "object": {
      "amount_due": 5000
    }
  }
}

These failures can be surprisingly difficult to diagnose. At first glance the webhook still looks correct — it arrives, it parses. But code that assumes currency exists will fail:

invoice.currency.toUpperCase()

This throws a runtime error when currency is undefined. Detecting the removed field before deployment lets you fix the code proactively.

How developers usually spot webhook schema changes

Most teams log payloads or use RequestBin, Hookdeck, or ngrok to inspect individual requests. Those tools help with delivery debugging, but they don't track schema evolution across production events — you usually only notice structural changes after something breaks. Often the webhook still returns a 200 response, which makes it look like everything succeeded even though downstream logic is failing.

If you're debugging webhook integration failures in production, see our guide on debugging webhook integration failures.

Monitoring webhook schemas automatically

Schema monitoring automates the detection process:

• Extract JSON structure from each payload
• Normalize schema paths for consistent comparison
• Compare schemas across events for the same event type
• Detect structural differences (added, removed, type changes)
• Classify breaking vs non-breaking changes

A normalized schema representation might look like:

id: string
type: string
data.object.id: string
data.object.amount_due: number
data.object.currency: string

When a later event omits data.object.currency, the diff would show:

Removed field: data.object.currency

Detecting webhook schema changes with HookHound

HookHound is a webhook schema monitoring tool that:

• Captures incoming webhook events
• Extracts payload schemas automatically
• Tracks schema versions over time
• Detects structural changes (added, removed, type changes)
• Alerts when breaking changes occur (Slack or email)

Example alert when a breaking change is detected:

When production schema monitoring pays off

Schema monitoring tends to pay off when you depend on Stripe (or other providers) for payments or critical workflows, or when several downstream systems consume webhook data — a single schema change can break more than one. It also helps when providers ship updates regularly, or when production debugging is expensive. Catching changes early reduces risk.

For a broader production setup, see our guide on production webhook monitoring.

Catching webhook changes before production breaks

Webhook payload schemas evolve over time. Fields are added, removed, or changed — often without prominent announcements. Monitoring structural changes helps you detect issues earlier and fix them before production breaks.

FAQ