Webhook Events

This is the annotated catalog of every event Flint can send to your endpoint. For each family it covers what triggers each event, what the data payload carries, and which event to build a given job on. It closes with the sequences you will actually see on the wire for real scenarios: a checkout payment, a refund, a dispute, a subscription renewal.

Two related pages cover the rest:

• To receive events (register endpoints, verify signatures, handle retries), start with Webhooks.
• For the always-current one-line list of every event type, see the live event catalog. This guide annotates that list.

The Event Envelope#

Every merchant event shares one envelope. Only data varies by family.

Here is a complete delivery, headers and body, for order.payment_succeeded:

POST /webhooks/flint HTTP/1.1
Content-Type: application/json
User-Agent: Flint-Webhooks/1.0
X-Flint-Webhook-ID: whev_1kmn0aExample
X-Flint-Event-Type: order.payment_succeeded
X-Flint-Webhook-Endpoint-ID: whep_1kmn0aExample
X-Flint-Signature: t=1783087200,v1=5f3a8c1d9b2e...
webhook-id: whev_1kmn0aExample
webhook-timestamp: 1783087200
webhook-signature: v1,K5oZfzN95Z8sExample=

{
  "webhook_event_id": "whev_1kmn0aExample",
  "event_type": "order.payment_succeeded",
  "payload_version": 1,
  "mode": "test",
  "merchant_id": "mer_1kmn0aExample",
  "created_at": "2026-07-03T14:00:00Z",
  "data": {
    "order_id": "ord_1kmn0aExample",
    "payment_intent_id": "pi_1kmn0aExample",
    "status": "paid",
    "payment_intent_status": "succeeded",
    "paid_money": { "amount": 9900, "currency": "USD" },
    "line_items": [
      {
        "order_line_item_id": "li_1kmn0aExample",
        "name": "Annual membership",
        "quantity": 1,
        "unit_price_money": { "amount": 9900, "currency": "USD" },
        "gross_money": { "amount": 9900, "currency": "USD" }
      }
    ]
  }
}

Delivery headers#

Verification itself is covered step by step in Webhooks.

Delivery Semantics That Shape Your Handler#

Three transport facts change how you consume every event on this page:

• Delivery is at least once. The same event can arrive twice. Dedupe on webhook_event_id.
• Success is a 2xx within 10 seconds. Anything else counts as a failed attempt. Queue slow work and respond immediately.
• Failed deliveries retry up to 9 times over roughly 30 hours. The full schedule is in the delivery contract.

Choosing the Right Event#

Most integrations need two or three events, not the whole catalog. Find your job in the left column and subscribe to the event in the middle.

Pick one primary event per job and make the handler idempotent. Subscribing to overlapping events for the same job is the most common cause of double fulfillment.

Event Catalog by Family#

Subscribe per endpoint with enabled_events; an empty list means every event. The tables below annotate every current event type, and the live event catalog always reflects the latest list.

Payment Intents#

Payload: a payment_intent object with payment_intent_id, status, and amount_money, plus order_id, customer_id, and cancellation_reason when set. Note the wrapper: this is the only family that nests its object under a key.

{
  "payment_intent": {
    "payment_intent_id": "pi_1kmn0aExample",
    "status": "succeeded",
    "amount_money": { "amount": 4200, "currency": "USD" },
    "order_id": "ord_1kmn0aExample",
    "customer_id": "cus_1kmn0aExample"
  }
}

There is no payment_intent.expired event; an expired authorization arrives as payment_intent.canceled. If your payments flow through orders, you can usually skip this family and listen at the order level instead.

Orders#

Payload: the order.payment_* events carry order_id, payment_intent_id, the order's public status, and payment_intent_status; authorization events add authorization_status; each event adds the money fields for its transition. order.refunded carries order_id, status, and the refund fields below. The full order.payment_succeeded body is shown in The Event Envelope.

A partial capture fires order.payment_captured without order.payment_succeeded. See Manual Capture for the full authorize-then-capture flow.

Order Fulfillment#

Payload: embeds the public order and fulfillment objects for the change, plus the shipment and package objects where relevant.

Checkout Sessions#

Payload: thin by design. Fetch the session or the order when you need details.

{
  "order_id": "ord_1kmn0aExample",
  "payment_intent_id": "pi_1kmn0aExample",
  "checkout_session_id": "cs_1kmn0aExample"
}

If you fulfill from order.payment_succeeded, treat this event as the trigger for checkout-specific work such as analytics or post-purchase messaging, not as a second fulfillment trigger. See Checkout Sessions.

Refunds#

Payload: refund_id, status, amount_money, payment_intent_id, and order_id, plus reason and failure_reason when set, per-payment splits in payment_refunds, and per-line-item detail in line_item_allocations.

{
  "refund_id": "ref_1kmn0aExample",
  "status": "succeeded",
  "amount_money": { "amount": 2500, "currency": "USD" },
  "payment_intent_id": "pi_1kmn0aExample",
  "order_id": "ord_1kmn0aExample",
  "payment_refunds": [
    {
      "payment_intent_id": "pi_1kmn0aExample",
      "amount_money": { "amount": 2500, "currency": "USD" },
      "refunded_tip_money": { "amount": 0, "currency": "USD" },
      "status": "succeeded"
    }
  ],
  "line_item_allocations": [
    {
      "order_line_item_id": "li_1kmn0aExample",
      "quantity": 1,
      "refunded_money": { "amount": 2500, "currency": "USD" }
    }
  ]
}

There is no refund.succeeded event. Success is refund.updated with status: "succeeded". See Refunds.

Disputes#

Payload: the full dispute: dispute_id, payment_intent_id, order_id, amount_money, public status, reason, and case_type, plus evidence state such as evidence_due_at, action_required, and evidence_submission_count.

Act on dispute.needs_response; the others keep your records current.

Subscriptions#

Payload: subscription_id, plan_id, and the plan's line_items; each event adds its own context fields, listed below.

{
  "subscription_id": "sub_1kmn0aExample",
  "plan_id": "plan_1kmn0aExample",
  "line_items": [
    {
      "name": "Pro plan",
      "quantity": 1,
      "unit_price_money": { "amount": 1900, "currency": "USD" },
      "gross_money": { "amount": 1900, "currency": "USD" }
    }
  ],
  "order_id": "ord_1kmn0aExample",
  "payment_intent_id": "pi_1kmn0aExample"
}

Subscriptions without a trial never fire subscription.activated; their first subscription.payment_succeeded is the activation signal. Each successful cycle also creates a regular order, so the cycle's order.payment_succeeded fires too. See Subscription Billing.

Invoices#

Payload: an invoice snapshot: invoice_id, order_id, invoice_number, status, refund_status, amount_due_money, and customer_id when set. Delivery events add the attempt: delivery_kind, delivery_channel, delivery_status, to_email, and error_message on failure.

See Invoicing.

Customers and Saved Payment Methods#

Payload: customer.created carries customer_id, email, and name; customer.updated carries customer_id, email, and updated_fields. payment_method.saved carries payment_method_id, customer_id, and card display details (card_brand, card_last4, card_exp_month, card_exp_year, plus card_wallet for wallet cards); payment_method.removed carries payment_method_id and customer_id.

payment_method.saved fires when the save completes, which can be after the buyer has left your page. Treat it as the durable signal that a card on file is usable.

Payouts#

Payload: the payout: payout_id, amount_money, status, method, initiated_by, fee fields, and payout_destination_id when set.

Payout Destinations and Settings#

Payload: the payout destination, setup session, or settings object that changed, with public status values.

Balances and Capabilities#

Payload: balance.updated carries the full balance (available, pending, held, and instant-available money). balance_transaction.* carries the transaction: balance_transaction_id, type, signed amount_money, fee_money, net_money, status, available_on, and a related_object reference back to its source. capability.updated carries the capability name, its status, and outstanding requirements.

balance_transaction.created is the backbone of reconciliation: one event per ledger entry, each linking back to its source object.

Event Sequences by Scenario#

Hosted checkout payment#

A buyer pays on a checkout session or payment link.

buyer pays on the hosted page
  -> payment_intent.succeeded       the charge settled
  -> order.payment_succeeded        the order is paid
  -> checkout_session.completed     the session finished; carries order_id
  -> balance_transaction.created    the charge hit your balance

Fulfill from order.payment_succeeded or checkout_session.completed, never both.

Manual capture#

You place a hold now and capture later. See Manual Capture.

confirm with manual capture
  -> payment_intent.requires_action        only if 3D Secure is required
  -> payment_intent.requires_capture       the hold is on
  -> order.payment_authorized              carries capturable_money

capture                                    void, or let the hold expire
  -> payment_intent.succeeded              -> payment_intent.canceled
  -> order.payment_captured                -> order.payment_authorization_voided
  -> order.payment_succeeded                  or order.payment_authorization_expired

A partial capture fires order.payment_captured without order.payment_succeeded.

Refund#

POST /v1/refunds
  -> refund.created                 status pending
  -> refund.updated                 status succeeded
  -> order.refunded                 order totals updated
  -> balance_transaction.created    the debit on your balance

if the refund fails
  -> refund.failed                  failure_reason says why

Act on refund.updated reaching succeeded, not on the create response.

Dispute#

card network opens a case
  -> dispute.created
  -> dispute.needs_response         evidence deadline running
you submit evidence
  -> dispute.updated                case under review
  -> dispute.won  or  dispute.lost
  -> dispute.closed

early-warning case
  -> dispute.prevented or dispute.warning_closed

Subscription billing#

signup completes
  -> subscription.created           plus customer.created and payment_method.saved on hosted signup
each successful cycle
  -> subscription.payment_succeeded carries the cycle's order_id
  -> order.payment_succeeded        the cycle's order, like any other order
trial ends
  -> subscription.activated

a renewal fails
  -> subscription.payment_failed
  -> subscription.past_due          retries are running
retries recover                     retries exhaust
  -> subscription.payment_succeeded -> subscription.canceled

The entitlement pattern: provision on subscription.payment_succeeded, warn on subscription.past_due, revoke on subscription.canceled.

Payout cycle#

funds scheduled to your bank
  -> payout.created -> payout.updated -> payout.paid
                                      -> payout.failed    funds return to your balance
after arrival
  -> payout.reversed                a completed payout was pulled back

Discovering Events at Runtime#

The catalog is machine readable. GET /v1/webhook-event-types returns every event type your endpoints can subscribe to:

curl "https://api.withflintpay.com/v1/webhook-event-types?page_size=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "event_type": "balance.updated",
      "event_sources": ["merchant", "installed_merchants"]
    },
    {
      "event_type": "balance_transaction.created",
      "event_sources": ["merchant", "installed_merchants"]
    }
  ],
  "request_id": "2f7c5a9d-6e4b-4f8a-9b73-1d8e4c6a0f25"
}

The event_type values are exactly what enabled_events accepts when you create or update an endpoint. Use this endpoint to validate your configuration in CI, or to build tooling that stays current as new events ship.

Test events and resends are walked through in Testing.

Partner App Events#

Partner apps are a separate event source with their own endpoints and a thinner envelope: no payload_version, mode, or merchant_id at the top level. partner_app_id identifies your app, and the merchant appears inside data.

{
  "webhook_event_id": "whev_1kmn0aExample",
  "event_type": "partner_app.install.created",
  "partner_app_id": "papp_1kmn0aExample",
  "created_at": "2026-07-03T14:00:00Z",
  "data": {
    "partner_app_id": "papp_1kmn0aExample",
    "partner_app_install_id": "pinst_1kmn0aExample",
    "merchant_id": "mer_1kmn0aExample",
    "status": "active",
    "granted_scopes": ["commerce.orders.read"]
  }
}

Endpoint setup, install tokens, and handling patterns are in Partner App Installs.

Common Mistakes#

• Fulfilling from two overlapping events. payment_intent.succeeded, order.payment_succeeded, and checkout_session.completed all fire for one hosted payment. Pick one primary event per job and dedupe on webhook_event_id.
• Assuming arrival order. Deliveries fan out and retry independently, so a later event can arrive first. Handle each event as a self-contained fact.
• Waiting for events that do not exist. There is no payment_intent.captured (a capture arrives as payment_intent.succeeded) and no refund.succeeded (success is refund.updated with status: "succeeded").
• Treating the payload as current state. data is a snapshot from created_at, and a retry can deliver it more than a day later. Fetch the resource before acting on fields that may have moved.
• Rejecting unknown event types. New event types ship over time, and endpoints subscribed to all events receive them immediately. Return a 2xx for types you do not handle; an error response burns retries on events you never wanted.

Next Steps#

• Webhooks: register endpoints, verify signatures, and process retries safely.
• Live event catalog: the always-current one-line list of every event type.
• Testing: test events, resends, and sandbox validation.
• Statuses & Lifecycles: the status values these events report.
• Manual Capture: the authorize-then-capture flow behind the order authorization events.
• Subscription Billing: plans, trials, and the billing lifecycle behind the subscription events.