Dispute and Pre-Dispute Alert webhooks

Flo now publishes two provider-neutral webhook families for the dispute journey. Four dispute.* events follow a provider dispute from creation to a final outcome, and two pre_dispute_alert.* events deliver early warnings before a dispute exists. Both use one stable Flo identity and an increasing sequence, so the same handler works whichever gateway or alert source produced the activity. The developer documentation now carries copy-pastable examples and worked guidance for every step of the integration.

Two new event families

• dispute.created opens the lifecycle for a dispute.id.
• dispute.updated reports a material change that is not yet an outcome, including an appeal.
• dispute.won and dispute.lost are terminal. A dispute never regresses past either outcome, and ambiguous outcomes are retained for review rather than reported.
• pre_dispute_alert.created raises an early warning with the amount, deadline, reason, and descriptive hints an alert source shares.
• pre_dispute_alert.updated reports a material change, including the moment Flo links the alert to a Flo payment.

The payloads name no gateway or alert network and carry no provider identifiers or raw statuses. Read the full catalog, examples, and lifecycle rules in Dispute events and Pre-Dispute Alert events, and the field-level reference in Dispute Payload and Pre-Dispute Alert Payload.

Subscribe and verify

Existing endpoints are not subscribed to the new families automatically. Add the event names to the events array with POST /v1/webhooks or PATCH /v1/webhooks/{id}, then verify each delivery's Flo-Signature header with the endpoint's signing secret before you act on it. The delivery guide has the request shape and the verification steps.

Handle deliveries safely

Deduplicate by eventId, then apply dispute and alert state only when the payload's sequence is higher than the one you stored for that dispute.id or preDisputeAlert.id. HTTP delivery order is not guaranteed, and this pair of checks keeps your records correct across retries, out-of-order arrival, and resends. The guide also documents how Flo classifies your endpoint's responses for retry, how to read delivery records, and how a resend replays a delivery under its original eventId. See Delivery records, replay, and resend.

Alerts before a link exists

A Pre-Dispute Alert is delivered to the client that owns it as soon as Flo can attribute it, which can be before Flo links it to any customer or payment. It arrives with an empty paymentIds, no user object, and a linkStatus of unmatched or action_required. When a link is verified later, the alert keeps the same id, sequence rises, and pre_dispute_alert.updated carries the linked payments. A worked handler that correlates by the descriptive hints first and upgrades to paymentIds without creating a second record is in Correlate an unlinked Pre-Dispute Alert.

What's included

• Webhooks: the dispute.created, dispute.updated, dispute.won, dispute.lost, pre_dispute_alert.created, and pre_dispute_alert.updated event types, accepted by the webhook endpoint routes and readable through the delivery record routes, which also gained a preDisputeAlertUuid field and filter.
• Disputes: a provider-neutral dispute and Pre-Dispute Alert contract with a stable Flo identity, normalized status, phase, reason, and link status, and an increasing sequence.
• Docs: the event catalog, payload reference, delivery guide, and terminology updated for both families, plus refreshed connector subscription lists so that every inbound event Flo processes is documented.

Developer notes

• item.charged_back is unaffected. It remains the money-movement event for a withdrawal, invoice.updated still reports a reinstatement, and neither is an alias of a dispute.* event.
• The deprecated REST compatibility routes for chargeback alerts and their settings remain available with the same envelopes, filters, fields, and status codes, and there is no fixed removal date. Prefer the canonical Pre-Dispute Alert and Pre-Dispute Alert Settings routes for new work.
• Re-check the inbound subscription list on the connector page for each gateway you use. The lists now include every event Flo processes, and the dispute and alert notifications among them are required for the new families to reach you.
• There are no removals in this release. No existing webhook subscription, payload shape, refund or chargeback event, or SDK export changes, and no action is required unless you adopt the new events.

Why it matters

Early alerts are time-sensitive, and delivering them before a link exists gives you the whole response window. Stable identities and sequenced lifecycles make dispute state safe to reconcile from webhooks alone, and the published guidance shortens the path from subscribing to a working, idempotent handler.