Webhook event types

The full catalog of Tokeflow webhook events for payments, refunds, disputes, payment methods, and subscriptions, with an example payload.

Tokeflow emits an event whenever something meaningful happens to a transaction, refund, dispute, stored payment method, or subscription. Subscribe your endpoint to the events you care about (you can filter by type when you configure the endpoint), then react to them as the source of truth for asynchronous outcomes.

Every event is delivered in the standard envelope described in Webhooks overview and signed as described in Verifying signatures. The type field carries one of the values below.

Treat events idempotently. Deduplicate on the event id, and when an event changes important state, reconcile against the API (e.g. GET /api/v1/transactions/:id) before acting. Events can arrive out of order or more than once.

Transaction events

Event	When it fires
`transaction.created`	A transaction was created and accepted for processing.
`transaction.pending`	The charge is awaiting an asynchronous outcome (e.g. PIX, boleto).
`transaction.pre_authorized`	Funds were authorized but not captured (`capture: false`).
`transaction.authorized`	The charge succeeded (authorized, and captured unless pre-auth only).
`transaction.capture_pending`	A capture was requested and is being processed.
`transaction.failed`	The charge was declined or could not be completed.
`transaction.canceled`	The transaction was canceled before completion.
`transaction.voided`	An authorization was voided before capture.
`transaction.charged_back`	A chargeback was opened against the transaction.
`transaction.expired`	A pending charge expired without completing (e.g. PIX/boleto not paid in time).

Refund events

Event	When it fires
`transaction.refund_created`	A refund was created.
`transaction.refund_pending`	The refund is being processed by the provider.
`transaction.refunded`	The transaction was fully refunded.
`transaction.partially_refunded`	A partial refund settled; a balance remains captured.
`transaction.refund_failed`	The refund could not be completed.
`transaction.refund_cancelled`	A pending refund was cancelled.

Dispute events

Event	When it fires
`transaction.dispute_created`	A dispute was opened by the cardholder's bank.
`transaction.dispute_updated`	New information or a status change on an open dispute.
`transaction.dispute_won`	The dispute was resolved in your favor.
`transaction.dispute_lost`	The dispute was resolved against you.
`transaction.dispute_closed`	The dispute was closed.

Payment method events

Event	When it fires
`payment_method.action_required`	A stored payment method needs attention — for example a card reported as no longer valid, or with no replacement available from the network. Prompt the customer to update it.

Subscription events

Event	When it fires
`subscription.created`	A subscription was created.
`subscription.renewed`	A renewal charge succeeded and the subscription advanced to the next period.
`subscription.dunning`	A renewal charge failed; the subscription entered dunning (retries).
`subscription.reactivated`	A subscription returned to `active` after dunning or a pause.
`subscription.upgraded`	The subscription moved to a higher-value offer.
`subscription.downgraded`	The subscription moved to a lower-value offer.
`subscription.payment_method_changed`	The subscription's payment instrument was changed.
`subscription.paused`	The subscription was paused.
`subscription.resumed`	A paused subscription was resumed.
`subscription.cancelled`	The subscription was cancelled.
`subscription.expired`	The subscription reached the end of its term and expired.

Example payload

A transaction.authorized event. The resource lives under data.object:

{
  "id": "evt_3f9a2b1c8d7e",
  "type": "transaction.authorized",
  "created_at": "2026-01-15T12:30:09.000Z",
  "data": {
    "object": {
      "id": "tx_777",
      "organization_id": "org_123",
      "merchant_id": "mrc_123",
      "order_id": "ord_001",
      "external_order_id": "order_888",
      "customer_id": "cust_123",
      "amount_authorized": 15000,
      "amount_captured": 15000,
      "currency": "BRL",
      "payment_method": "credit_card",
      "charge_type": "payment",
      "country": "BR",
      "status": "authorized",
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:09.000Z"
    }
  }
}

The shape of data.object matches the corresponding API resource — a transaction for transaction.* events, a refund for refund events, a subscription for subscription.* events, and so on. See the API reference for each object's full schema.

Handling guidance

Acknowledge fast. Return a 2xx within a few seconds and do the real work asynchronously. Slow or failing responses trigger retries.
Deduplicate on id. The same event may be delivered more than once.
Don't trust order. Use the resource's own status (or a fresh API read) rather than assuming events arrive in sequence.
Verify every delivery. Reject any request whose signature does not validate — see Verifying signatures.