Brass mailbox receiving a stack of sealed envelopes, symbolizing a webhook inbox for payment disputes

Stripe Dispute Webhooks: Building a Chargeback Evidence Pipeline

•12 min read

Most teams discover their dispute handling is broken the same way: a chargeback closes as lost because nobody saw it in time, or someone submitted half the evidence by accident. This guide is about Stripe dispute webhooks and the system you build behind them: how to receive the events safely, model disputes in your own database, assemble evidence from order data automatically, stage it for review and never miss a deadline. It is written for developers, CTOs and technical founders who own the payments code, and it focuses on Stripe because its Disputes API is well documented, but the architecture applies to any processor.

If you want the business side first (which policies, descriptors and customer-service habits reduce chargebacks before they happen), read our 9-step guide to preventing chargebacks in an online store. Here we assume the dispute already exists and the question is how your software responds.

What the platform actually tells you

Before designing anything, pin down the facts your system has to respect:

  • Stripe emits charge.dispute.created, charge.dispute.updated and charge.dispute.closed for the dispute lifecycle, and radar.early_fraud_warning.created when an issuer or network flags a charge as potentially fraudulent, typically before a formal dispute.
  • The Dispute object exposes charge as an ID and a nullable payment_intent, so you usually need to retrieve the Charge to link the dispute to your order (Stripe docs).
  • Stripe does not guarantee delivery order, and event timestamps are in whole seconds, so it advises against ordering by created and recommends fetching the current object from the API instead (summary by Chargeflow, citing Stripe's webhook docs).
  • According to Stripe, you usually have 7 to 21 days to respond depending on the card network, and the issuer then usually takes 60 to 75 days to decide (via Chargeflow). Your dispute records live for months, not minutes.
  • On the update endpoint, "updating any field in the hash will submit all fields in the hash for review", the combined character count of all evidence fields is limited to 150,000, and submit defaults to true (Update a dispute).
  • A dispute can, in rare cases, move from lost to won outside the normal lifecycle, and a single payment can have more than one dispute (Chargeflow).

Each of these turns into a design rule below.

Architecture: inbox, worker, evidence builder, scheduler

A dispute pipeline that survives real traffic has four parts:

  1. Webhook inbox. A thin HTTP endpoint that verifies the signature, stores the raw event once, and returns 2xx. No business logic.
  2. Sync worker. Reads pending events, fetches the current Dispute from the API, upserts your disputes table and triggers side effects (pause fulfillment, revoke access, notify).
  3. Evidence builder. Maps your order, shipping, login and policy data to Stripe's evidence fields and stages them without submitting.
  4. Scheduler and reconciler. Escalates disputes approaching evidence_details.due_by and periodically lists disputes from the API to catch anything a webhook missed.

The split matters because the four parts fail differently. The inbox must be fast and almost never fail; the worker can retry; the evidence builder depends on several internal systems that may be slow; the reconciler is your safety net when everything else goes wrong.

Step 1: a webhook inbox that does almost nothing

Verify the signature against the raw request body (parsing JSON first breaks verification), then insert the event with its ID as a unique key. The Stripe libraries apply a default timestamp tolerance of five minutes to the signature, which also limits replay attacks (Chargeflow).

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      req.headers["stripe-signature"],
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch {
    return res.status(400).send("invalid signature");
  }

  // Idempotent insert: duplicates are ignored, not errors
  await db.query(
    `INSERT INTO webhook_inbox (event_id, type, object_id, payload, received_at)
     VALUES ($1, $2, $3, $4, now())
     ON CONFLICT (event_id) DO NOTHING`,
    [event.id, event.type, event.data.object.id, event]
  );

  res.sendStatus(200); // acknowledge fast; the worker does the real work
});

Trade-off: processing inline is simpler and fine at low volume, but any slow call (fetching the charge, uploading a file, posting to Slack) risks timeouts and redeliveries. An inbox table costs one migration and buys you replayability, an audit trail and a clean place to measure lag.

Step 2: a data model that mirrors Stripe without depending on event order

Store Stripe's status as-is and keep your own operational fields next to it. Do not try to compute status from the sequence of events.

CREATE TABLE disputes (
  stripe_dispute_id   text PRIMARY KEY,
  stripe_charge_id    text NOT NULL,
  payment_intent_id   text,             -- nullable in Stripe's object
  order_id            bigint REFERENCES orders(id),
  amount              integer NOT NULL, -- minor units, may differ from the charge
  currency            char(3) NOT NULL,
  reason              text NOT NULL,
  stripe_status       text NOT NULL,    -- copied verbatim from the API
  due_by              timestamptz,      -- evidence_details.due_by
  evidence_state      text NOT NULL DEFAULT 'none', -- none | drafted | staged | submitted
  owner_user_id       bigint,
  last_synced_at      timestamptz NOT NULL,
  closed_at           timestamptz
);
CREATE INDEX ON disputes (due_by) WHERE evidence_state <> 'submitted';
CREATE INDEX ON disputes (stripe_charge_id); -- one charge can have several disputes

Note the index on stripe_charge_id rather than a unique constraint: since a payment can be disputed more than once, a one-to-one assumption between orders and disputes will eventually break.

Step 3: the worker fetches, then upserts

The worker treats each event as a notification that "something changed", not as the source of truth. It retrieves the object and writes whatever the API returns.

async function processDisputeEvent(row) {
  const dispute = await stripe.disputes.retrieve(row.object_id);
  const charge = await stripe.charges.retrieve(dispute.charge);
  const orderId = await findOrderByCharge(charge); // e.g. from charge.metadata.order_id

  await db.query(
    `INSERT INTO disputes (stripe_dispute_id, stripe_charge_id, payment_intent_id, order_id,
       amount, currency, reason, stripe_status, due_by, last_synced_at)
     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,to_timestamp($9),now())
     ON CONFLICT (stripe_dispute_id) DO UPDATE SET
       stripe_status = EXCLUDED.stripe_status,
       due_by = EXCLUDED.due_by,
       amount = EXCLUDED.amount,
       last_synced_at = now()`,
    [dispute.id, charge.id, dispute.payment_intent, orderId, dispute.amount,
     dispute.currency, dispute.reason, dispute.status, dispute.evidence_details?.due_by]
  );

  await runSideEffectsOnce(dispute, orderId); // keyed by dispute id + effect name
  await markProcessed(row.event_id);
}

Because the worker always reads the latest state, a late charge.dispute.updated arriving after charge.dispute.closed simply writes the same closed status again. Side effects (pausing a shipment, suspending a subscription, notifying the team) should be recorded in a separate table keyed by dispute ID and effect name so a retry never sends two alerts or cancels twice.

Building the evidence: capture at checkout, not after the dispute

The evidence builder can only use data you stored when the order happened. This is the part most teams cannot fix retroactively, so design the order data model with disputes in mind:

  • Identity and device: customer email, name, billing address, purchase IP. These map to fields such as customer_email_address, customer_name, billing_address and customer_purchase_ip.
  • Fulfillment: carrier, tracking number, ship date and proof of delivery, mapping to shipping_carrier, shipping_tracking_number, shipping_date and shipping_documentation.
  • Digital goods and services: login and usage events with timestamps, mapping to access_activity_log and service_date.
  • Policies: the exact version of the refund and cancellation policy the customer accepted, with a timestamp, mapping to refund_policy and cancellation_policy.
  • Communication: support tickets and emails with the customer, as files or text.

Files such as delivery confirmations or receipts are uploaded first with the Files API (purpose dispute_evidence) and then referenced by ID in the evidence hash. The Disputes API reference lists every field, and Stripe's dispute guides explain which fields matter for which reason, so the builder should branch on dispute.reason rather than send everything every time.

function buildEvidence(dispute, order) {
  const base = {
    customer_email_address: order.email,
    customer_name: order.customerName,
    customer_purchase_ip: order.purchaseIp,
    product_description: order.summary,
  };
  switch (dispute.reason) {
    case "product_not_received":
      return { ...base,
        shipping_carrier: order.carrier,
        shipping_tracking_number: order.trackingNumber,
        shipping_date: order.shippedOn,
        shipping_documentation: order.deliveryProofFileId };
    case "subscription_canceled":
      return { ...base,
        cancellation_policy: order.cancellationPolicyFileId,
        access_activity_log: order.accessLogText };
    default:
      return { ...base, uncategorized_text: order.timelineText };
  }
}

Keep generated text well below the 150,000-character combined limit. A concise timeline with dates beats a dump of raw logs, both for the limit and for the person at the bank who reads it.

Stage first, submit deliberately

The most dangerous default in this API is submit: true. If any process updates evidence without explicitly passing submit: false, Stripe submits everything immediately, and the arbitration docs warn that adding or updating evidence without submit=false submits all staged evidence. In practice that means a half-finished automated draft can become your final answer.

// Automated builder: always stage
await stripe.disputes.update(dispute.id, {
  evidence: buildEvidence(dispute, order),
  submit: false,
});

// Human approval (or an explicit rule) triggers the real submission
await stripe.disputes.update(dispute.id, { submit: true });

Wrap the Stripe client so that the only code path able to send submit: true is the approval action, and make that path check evidence_state and current stripe_status first. Pass an idempotency key on these POST requests so a retried approval does not cause a confusing double update.

Smart Disputes versus your own builder

Stripe offers Smart Disputes to automate evidence collection and submission for eligible disputes, and the Dispute object exposes a setting with values like manual, prefer_manual, prefer_smart_disputes and smart_disputes that decide which packet is used (Dispute object). The trade-off is straightforward: Smart Disputes uses what Stripe already knows and needs little engineering; your own builder can include evidence Stripe never sees, such as delivery photos, in-app usage or support conversations. Many teams combine them: let automation handle low-value cases and route high-value or ambiguous ones to the manual pipeline. Whatever you choose, make the choice explicit in configuration instead of letting it depend on whichever code happened to touch the dispute first.

Deadlines, reconciliation and early warnings

Deadline scheduler. Run a job that selects disputes where evidence_state <> 'submitted' and due_by is approaching, and escalates in tiers (owner, then team lead). Always compute and display deadlines in UTC alongside the reviewer's local time; teams split between Mexico City, Bogotá and the US will otherwise argue about what "due tomorrow" means.

Reconciler. Webhooks can fail: an endpoint was down longer than the retry window, a secret was rotated incorrectly, or an event type was never subscribed. A daily job that lists recent disputes and compares them with your table catches all of these.

for await (const d of stripe.disputes.list({ created: { gte: thirtyDaysAgo }, limit: 100 })) {
  const local = await getDispute(d.id);
  if (!local || local.stripe_status !== d.status) {
    await enqueueSync(d.id); // same code path as the webhook worker
  }
}

Reusing the worker's code path is important: reconciliation that writes to the database through a different function will drift from it.

Early fraud warnings. radar.early_fraud_warning.created arrives before a formal dispute in many cases. Route it to the same inbox and decide by rule whether to refund proactively, cancel fulfillment or just flag the order. Refunding avoids the dispute but gives up the revenue; fighting keeps the option to win but risks a dispute that counts against you. Make the rule depend on amount, whether the order already shipped and whether the customer has history with you.

Appeals. If a dispute goes to pre-arbitration, Stripe accepts evidence through evidence.appeal, and according to its docs, not submitting within 20 days means you implicitly assume liability (Stripe arbitration docs). Model this as another evidence round on the same dispute, with its own deadline.

Common mistakes

  • Parsing the JSON body before signature verification, so every signature check fails in production.
  • Doing business logic inside the webhook handler and timing out under load.
  • Deriving dispute status from event order instead of fetching the object.
  • Assuming one dispute per order, or that the disputed amount equals the charge amount.
  • Letting automated code update evidence without submit: false.
  • Storing no purchase IP, policy version or delivery proof at checkout, then trying to reconstruct it weeks later.
  • Having no reconciliation job, so a missed webhook becomes a missed deadline.
  • Sending side effects (emails, cancellations) without deduplication.

Implementation checklist

  1. Subscribe to charge.dispute.created, charge.dispute.updated, charge.dispute.closed and radar.early_fraud_warning.created.
  2. Verify signatures on the raw body; store events in an inbox with a unique event ID.
  3. Process asynchronously; always retrieve the current Dispute and Charge from the API.
  4. Model disputes with Stripe status verbatim, due_by, evidence state, owner and order link.
  5. Capture evidence data at checkout and fulfillment time, including policy versions.
  6. Build evidence per reason code; upload files with purpose dispute_evidence.
  7. Stage with submit: false; restrict submit: true to an approval path.
  8. Escalate approaching deadlines; reconcile daily against the API.
  9. Deduplicate side effects; log every evidence change for audit.

If your store runs on a custom stack and this pipeline spans checkout, fulfillment and support systems, this is the kind of integration we design in our custom software projects. For stores still being planned, it is far cheaper to build the evidence fields into the online store from day one than to retrofit them.

Frequently asked questions

Do I need a queue, or is a database table enough for the inbox?

For most stores a database table with a unique event ID and a worker that polls it is enough, and it is easier to inspect and replay. Move to a dedicated queue when volume or latency requirements make polling impractical; keep the unique event ID either way.

Can I trust the dispute object inside the webhook payload?

It is a snapshot from when the event was created. Because delivery order is not guaranteed, fetch the current Dispute from the API before writing state, and use the payload only to know which object to fetch.

Should evidence submission be fully automated?

Only where you are confident in the data and the case is low risk. Since any evidence update submits by default, keep automated code on submit: false and require an explicit approval, human or rule-based, for the final submission.

Comments

No comments yet. Be the first to share what you think.

Leave a comment

It is never published.