Delivery

Flo webhooks are delivered asynchronously.

What To Assume

• delivery is asynchronous
• delivery is retry-backed
• delivery should be treated as at-least-once
• strict ordering is not guaranteed across all event families

Ordering

Ordering is best-effort and should not be treated as a strict guarantee across all event families.

Consumers should:

• treat webhook delivery as asynchronous
• fetch current resource state when absolute ordering matters
• make handlers idempotent

Idempotency

Consumers should implement idempotency in their handlers.

In practice, that means your endpoint should be able to safely process the same Flo event more than once without duplicating side effects. Use the top-level eventId as the delivery key you persist for deduping retries. Automatic retries reuse the same eventId for the same delivery, while a later replay or resend is treated as a new delivery and can have a different eventId.

Retries

When delivery fails, Flo retries with backoff before eventually marking the event as failed internally.

Your handler should therefore:

• return quickly
• perform idempotent writes
• avoid assuming a single delivery attempt
• be tolerant of delays between the billing activity and webhook arrival

Signature

Each webhook delivery includes a Flo-Signature header with this format:

Flo-Signature: t=1712841600,v1=abcdef123456...

To verify a delivery:

• read the raw request body before JSON parsing
• compute an HMAC SHA-256 using your webhook signing secret
• sign the string ${timestamp}.${rawRequestBody}
• compare the result to the v1 value in Flo-Signature

Forward Scope

Endpoint CRUD, monitoring, replay, resend, and delivery controls will be documented as they are released.