Webhooks

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.

Build Against Flo Terms

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, or invoice contains the normalized Flo payload for that event.

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 Families

Flo currently sends events for three resource families:

• subscription
• item
• invoice

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
• invoice.created
• invoice.updated
• invoice.deleted
• invoice.paid
• invoice.overdue

What Clients Receive

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, or invoice
• optional invoice and payment context via invoiceDetails
• optional related root-level subscription and item enrichment on invoice events

See Events for the event catalog and examples, and Payloads for field-level schema details.

Versioning

• Current event version: v1
• New integrations should treat v1 as the public contract