Choosing Webhook Events

Flint can emit several events from one business flow. A successful invoice payment for a subscription might create:

payment_intent.succeeded
order.payment_succeeded
invoice.paid
subscription.payment_succeeded
balance_transaction.created

That is intentional. Each event describes the same flow at a different level of the product model. Subscribe to the event closest to the job your system owns.

Payment Reconciliation#

Use payment intent and money movement events when your system needs payment-rail state or ledger reconciliation.

Good fits:

payment_intent.succeeded
payment_intent.payment_failed
payment_intent.requires_action
balance_transaction.created
balance_transaction.updated

Fetch the payment intent or balance transaction before posting irreversible ledger entries if you receive an older delivery after a newer one.

Order Fulfillment#

Use order events when your system ships goods, commits inventory, starts service delivery, or mirrors an OMS.

Good fits:

order.created
order.updated
order.closed
order.payment_succeeded
order.inventory_exception.created
order.inventory_exception.resolved
order.reconciliation_exception.created
order.fulfillment.status_changed

Use resource_updated_at to discard stale order mirror updates. Payment-driven order money changes have dedicated order payment events; generic order.updated is for material order edits. Fetch the order when you need the full current shape before taking an irreversible action.

Invoicing, AR, And Dunning#

Use invoice events when your system owns accounts receivable, invoice sync, or collection follow-up.

Good fits:

invoice.created
invoice.opened
invoice.updated
invoice.payment_failed
invoice.payment_attempt_canceled
invoice.payment_attempt_expired
invoice.collection_blocked
invoice.collection_block_resolved
invoice.paid
invoice.voided

invoice.sent is an email delivery signal. Use invoice.opened when you need to know that an invoice is collectible.

Subscription Entitlements#

Use subscription events when your system grants, suspends, or removes recurring entitlements.

Good fits:

subscription.created
subscription.activated
subscription.payment_succeeded
subscription.payment_failed
subscription.past_due
subscription.paused
subscription.resumed
subscription.canceled

Prefer subscription events over invoice or payment intent events when the action is about access to a recurring product.

Saved Billing Credentials#

Use payment method events when your system manages saved cards or off-session billing readiness.

Good fits:

payment_method.saved
payment_method.failed
payment_method.removed

payment_method.failed means an asynchronous setup flow failed and the saved method did not become usable.

Platform Merchant Readiness#

Use merchant readiness and capability events when your platform needs to know whether a managed merchant can accept payments, receive payouts, or complete onboarding requirements.

Good fits:

merchant.readiness.updated
capability.updated

merchant.readiness.updated is the broader platform-facing signal. It uses Flint readiness vocabulary for payments, payouts, and onboarding requirements. Do not depend on processor-shaped booleans.

Checkout Recovery And Cart Cleanup#

Use checkout session events when your system manages hosted checkout links, cart recovery, or pending reservations.

Good fits:

checkout_session.completed
checkout_session.closed
checkout_session.expired
checkout_session.invalidated

An invalidated session can mean the buyer is actively using a newer checkout session. Check reason and superseding_checkout_session_id before treating it as abandonment.

When In Doubt#

Use the highest-level event that directly matches the action your system will take. Fetch the public resource before irreversible side effects, and use resource_updated_at or a version field to ignore stale deliveries.