Fix: n8n webhook failing after an upstream API schema change

    When Stripe, HubSpot, Typeform, or another upstream API changes its payload, n8n often fails downstream without useful context. Validate the full item batch, preserve the raw payload, and route schema drift to an explicit recovery path instead of blindly asking an LLM to repair it.

    Last updated 2026-09-21~5 min read
    n8nWebhooksHTTP RequestCode nodeError Trigger

    Last updated: 2026-06-08 · Tested on: n8n 1.x · Read time: ~5 min

    Symptoms — what you're seeing

    • An upstream webhook or HTTP Request succeeds, but a later n8n node fails after the provider changes its response shape
    • An expression such as $json.customer.phone resolves to undefined or null without an obvious change in your n8n workflow
    • The workflow works for some records but fails for records from a different account, region, API version, or event type
    • A Code, IF, Switch, Google Sheets, CRM, or database node receives a different data type than it expects
    • The execution is marked as failed, but your operational alert does not show the raw payload that caused the failure

    Why this happens

    Upstream APIs change more often than the downstream expressions in an n8n canvas. A provider can move a value one level deeper, return null instead of a string, rename a webhook key, add a new event variant, or return an error object with HTTP 200. n8n then evaluates the payload against the old contract.

    This is not an auto-healing problem first. It is a contract and observability problem. The safe fix is to put a validation boundary between the webhook and the rest of the workflow. That boundary records the original item, identifies the schema version or failure reason, and sends only validated data downstream.

    If the failure starts at the webhook itself, first check the webhook URL, HTTP method, response mode, and incoming payload. My GoHighLevel webhook diagnostic covers the same first checks for GHL.

    The fix, step by step

    1. Capture the raw request before transforming it. Put the validation boundary immediately after the Webhook or HTTP Request node. Store the original body, headers needed for diagnosis, provider name, event type, and received timestamp. Do not overwrite the raw body with a normalized object.
    2. Inspect the complete batch. Open the execution data and check every item, not just the first one. A single execution can contain valid records followed by a malformed record. If you use a Code node, start with $input.all(), not $input.first().
    3. Define the contract that your downstream nodes actually require. List required keys, accepted types, and allowed nulls. Do not copy the entire provider response into every downstream expression. Normalize the small internal object that the rest of the workflow needs.
    4. Validate each item and separate valid data from drift. This Code node pattern keeps the item-level result visible. Replace the example required keys with the fields in your real contract before publishing it:
    5. // Code node: Run Once for All Items
      const inputItems = $input.all();
      const requiredKeys = ["id"]; // Replace with the field names your real contract requires
      
      return inputItems.map((item, index) => {
        const raw = item.json;
        const missing = requiredKeys.filter((key) => {
          return raw[key] === undefined || raw[key] === null;
        });
      
        const valid = missing.length === 0 && typeof raw === "object";
      
        return {
          json: {
            ...raw,
            _contract: {
              valid,
              itemIndex: index,
              missing,
              receivedAt: new Date().toISOString(),
            },
            _rawPayload: raw,
          },
          pairedItem: { item: index },
        };
      });
    6. Route on the validation result. Add an IF node after the Code node and test $json._contract.valid. Send valid items to the normal workflow. Send invalid items to a quarantine branch that stores the raw payload, provider, event type, missing keys, and execution ID. Do not pass a guessed repair into billing, CRM updates, or customer notifications.
    7. Make known changes deterministic. If Stripe moved a field or Typeform changed a key, add an explicit mapping for that provider and schema version. A Set node, Edit Fields node, or Code node with named mappings is easier to test than a general-purpose repair prompt. If you use an AI step for an unknown shape, validate its output against the same contract before routing it to production.
    8. Add retry logic only for transient failures. A 429 or 5xx response can justify a Wait and retry path; a payload missing a required key cannot. The n8n 429 rate-limit pattern shows why retrying a deterministic schema failure just repeats the same bad execution.
    9. Test with recorded payloads. Save one valid payload, one payload with a missing key, one payload with an unexpected null, one payload with the changed nesting, and one multi-item batch. Replay all five through a test workflow. Confirm that valid items continue, invalid items are quarantined, and no item disappears silently.

    Stuck on this for more than 30 minutes? Book a 30-min scope call. I'll get on Zoom, inspect the execution data and contract boundary, and either fix it on the call or scope what it'll take. No upsell, no decks.

    Common variations

    • Nested field changed. The provider moved customer.phone to another object or changed the event-specific nesting. Normalize the provider response once, then keep downstream expressions pointed at your internal shape.
    • Field changed from a string to an object. This often breaks database, spreadsheet, and CRM nodes. Validate the type explicitly instead of coercing every object to [object Object].
    • Unexpected null in an otherwise valid response. Treat nullability as part of the contract. Use a safe fallback only when the business meaning is known; otherwise quarantine the item.
    • Webhook key renamed. Keep the raw request and add a versioned mapping. Do not silently accept both old and new keys unless you log which shape arrived.
    • One item breaks a batch. Map and validate every item. A guard that checks only the first item is not a batch safety mechanism.
    • Workflow fails silently after an API response. Configure an Error Trigger workflow to alert and persist execution details. It is a recovery and observability path, not a mechanism that invisibly resumes the original run.

    When this isn't the issue

    If the upstream payload is still valid, follow these diagnostic forks:

    • The webhook never arrives. Check the URL, method, authentication, response status, and provider delivery log. For GoHighLevel, start with the webhook-not-receiving-data checklist.
    • The request arrives but the workflow stops on an HTTP Request node. Inspect the status code and response body. A 401, 403, 429, or 5xx is a transport or authentication problem, not schema drift.
    • The workflow runs on the wrong schedule or timezone. Check the workflow timezone and Schedule Trigger configuration. That is a separate failure mode covered in the n8n schedule trigger timezone fix.
    • The Error Trigger workflow does not alert. Confirm that it is an active, separate error workflow and that its notification node has valid credentials. Test it with a controlled failure instead of waiting for production drift.

    For production workflows, I build the validation boundary, quarantine path, retries, and monitoring as one n8n architecture. Book a 30-min scope call or email Basit with an example execution and the upstream API involved.

    Related pages

    Need this workflow customized or debugged? Book a 30-min scope call →

    Stuck configuring this workflow?

    I build and fix n8n workflows for agencies and SaaS teams. 30-minute scope call — bring the problem, leave with an estimate.

    Related pages