Why Your Stripe Webhook Schema Breaks on Refunds (and How to Fix It)

You're integrating Stripe webhooks. You paste a payment_intent.succeeded payload into a schema generator, wire the schema into your handler with Ajv, and it passes every test. Then production sends a payment_intent.payment_failed event — last_payment_error is now an object, payment_method is null — and your validator throws on a payload Stripe sent correctly. The schema was wrong from the start, because it was built from one sample. The fix is to generate it from several event payloads and merge them, so optional and nullable fields are detected automatically.

The happy-path payload that fools you

Here's a simplified payment_intent.succeeded data object (the real one has more fields; these are the stable ones that matter for the example):

{
  "id": "pi_3Success",
  "object": "payment_intent",
  "amount": 4999,
  "currency": "usd",
  "status": "succeeded",
  "customer": "cus_Abc123",
  "description": "Order #1001",
  "last_payment_error": null,
  "payment_method": "pm_1Card"
}

Feed that single sample to a normal schema generator and you get this — note last_payment_error typed as null, and customer, description, and payment_method all marked required strings:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id":                 { "type": "string" },
    "object":             { "type": "string" },
    "amount":             { "type": "integer" },
    "currency":           { "type": "string" },
    "status":             { "type": "string" },
    "customer":           { "type": "string" },
    "description":        { "type": "string" },
    "last_payment_error": { "type": "null" },
    "payment_method":     { "type": "string" }
  },
  "required": ["id", "object", "amount", "currency", "status",
               "customer", "description", "payment_method"]
}

It validates the success case perfectly. It is also a production bug waiting for the first failed payment.

The event that breaks it

Now a real payment_intent.payment_failed arrives. The card was declined, so Stripe populates last_payment_error with an object and leaves the payment fields empty:

{
  "id": "pi_3Failed",
  "object": "payment_intent",
  "amount": 4999,
  "currency": "usd",
  "status": "requires_payment_method",
  "customer": "cus_Def456",
  "description": null,
  "last_payment_error": {
    "code": "card_declined",
    "message": "Your card was declined.",
    "type": "card_error"
  },
  "payment_method": null
}

Against the single-sample schema, this valid Stripe payload fails validation in three separate ways.

Why it breaks: three causes

• Optional fields were marked required. The schema requires description and payment_method as strings. The failed event sends description: null and payment_method: null — both rejected.
• Field types were inferred too narrowly. last_payment_error was null in your one sample, so the schema froze its type as null. A failed event sends an object there, which does not match.
• Event payloads legitimately diverge. Every Stripe event shares one envelope — id, type, api_version, and a data.object — but the object inside data differs by event type and outcome, and is rendered per the api_version at creation time. Different shapes are expected. See Stripe's event types reference and webhooks guide.

You can spend an afternoon patching the schema by hand — flip last_payment_error to an object, make three fields optional, add null to their types — and still miss the next event type. There's a faster, more reliable way.

The fix: infer from multiple event samples

Capture a few different events and merge them. Add a third — a canceled PaymentIntent, which nulls or omits even more:

{
  "id": "pi_3Canceled",
  "object": "payment_intent",
  "amount": 1500,
  "currency": "usd",
  "status": "canceled",
  "customer": null,
  "last_payment_error": null,
  "payment_method": null
}

Paste all three — succeeded, payment_failed, canceled — into the Multi-Sample Schema Generator and merge. Fields missing or null in some events become optional or nullable; last_payment_error becomes "object or null". One schema now covers all three outcomes:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id":       { "type": "string" },
    "object":   { "type": "string" },
    "amount":   { "type": "integer" },
    "currency": { "type": "string" },
    "status":   { "type": "string" },
    "customer":       { "type": ["string", "null"] },
    "description":    { "type": ["string", "null"] },
    "payment_method": { "type": ["string", "null"] },
    "last_payment_error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code":    { "type": "string" },
            "message": { "type": "string" },
            "type":    { "type": "string" }
          },
          "required": ["code", "message", "type"]
        },
        { "type": "null" }
      ]
    }
  },
  "required": ["id", "object", "amount", "currency", "status"]
}

Notice what merging worked out automatically: customer, description, and payment_method are now nullable and no longer required; last_payment_error accepts both the error object and null; and only the fields present in every event stayed in required.

Wire it into your handler

Validate incoming events with Ajv against the merged schema — after verifying the signature:

const Ajv = require("ajv");
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(paymentIntentSchema); // the merged schema

app.post("/webhook", (req, res) => {
  // 1. Authenticity: verify the Stripe signature first.
  const event = stripe.webhooks.constructEvent(
    req.body, req.headers["stripe-signature"], endpointSecret
  );

  // 2. Structure: validate the payload shape.
  if (!validate(event.data.object)) {
    console.error("Unexpected payload shape:", validate.errors);
    return res.status(400).send("Bad payload");
  }

  // 3. Handle the event...
  res.json({ received: true });
});

Schema validation is not signature verification

These solve different problems and you want both. Signature verification — using the Stripe-Signature header and your endpoint secret — proves the request really came from Stripe and wasn't tampered with; do it first and reject anything that fails. Schema validation then confirms the payload has the structure your code expects. A valid signature on an unexpected shape, or a perfect shape with a bad signature, are both failures.

Webhook schemas evolve — re-merge periodically

Stripe adds fields to payloads over time, and the object you receive is rendered per the API version pinned to your endpoint. New optional fields are usually non-breaking, but when you adopt a new event type or bump your API version, capture a fresh sample and re-merge. Keeping the schema generated from real payloads — rather than hand-maintained — makes that a 30-second task instead of an audit.