WebhooksCopy Anchor Link

Flo webhooks are normalized outbound events sent by Flo.

Clients should integrate against the Flo contract only. The underlying billing gateway is an implementation detail and should not affect webhook consumers.

To create an endpoint and choose which events it receives, including filters by product or product tag, see Webhook configuration.

Build Against Flo TermsCopy Anchor Link

Every webhook payload is designed to be consumed in Flo terms:

• eventId identifies the Flo delivery record for the webhook sent to that endpoint.
• eventType tells you what happened in Flo.
• objectType tells you which Flo resource family changed.
• user.id is the Flo user id.
• user.clientUserId is your client-defined user id as stored by Flo.
• subscription, item, invoice, payment, dispute, or preDisputeAlert contains the normalized Flo payload for that event.
• On dispute and Pre-Dispute Alert events, user carries only id and clientUserId, and it is omitted when Flo cannot resolve exactly one user.

On invoice events, Flo may also include root-level subscription and/or item when the invoice is linked to a local transaction that resolves those checkout records. Optional fields such as invoiceDetails.gatewayEventType and these related root-level objects can provide extra trace context, but they should not be the basis of your integration logic.

Event FamiliesCopy Anchor Link

Flo currently sends events for six resource families:

• subscription
• item
• invoice
• payment
• dispute
• pre_dispute_alert (payload root preDisputeAlert)

Those families currently map to these Flo event types:

• subscription.created
• subscription.updated
• subscription.cancelled
• subscription.renewed
• subscription.reactivated
• subscription.paused
• subscription.resumed
• subscription.expired
• item.purchased
• item.refunded
• item.charged_back
• invoice.created
• invoice.updated
• invoice.deleted
• invoice.payment_failed
• invoice.paid
• invoice.overdue
• payment.authorized
• payment.capture_failed
• payment.authorization_voided
• payment.authorization_expired
• dispute.created
• dispute.updated
• dispute.won
• dispute.lost
• pre_dispute_alert.created
• pre_dispute_alert.updated

The dispute and Pre-Dispute Alert families describe a case, not a money movement. A withdrawal or reinstatement caused by a dispute still arrives through item.charged_back and invoice.updated. See Dispute events and Pre-Dispute Alert events.

What Clients ReceiveCopy Anchor Link

Each delivered webhook contains one Flo event payload. The top-level eventId identifies that specific Flo delivery record.

That payload includes:

• a delivery identifier via eventId
• a Flo event classification via eventType and objectType
• the Flo user via user
• a normalized resource payload via subscription, item, invoice, payment, dispute, or preDisputeAlert
• optional invoice and payment context via invoiceDetails
• optional related root-level subscription and item enrichment on invoice events
• optional root-level payment on item.purchased events: the Flo payment behind the purchase, described in Item Purchase Payment

See Events for the event catalog and examples, and Payloads for field-level schema details. For the inbound PayPal event catalog when a direct PayPal gateway is configured, see PayPal webhook events.

VersioningCopy Anchor Link

• Current event version: v1
• New integrations should treat v1 as the public contract
• Dispute and Pre-Dispute Alert events are published at v1 alongside the existing families