Tipos de eventos de webhook

O catálogo completo de eventos de webhook do Tokeflow para pagamentos, reembolsos, disputas, métodos de pagamento e assinaturas, com um exemplo de payload.

O Tokeflow emite um evento sempre que algo relevante acontece com uma transação, reembolso, disputa, método de pagamento armazenado ou assinatura. Inscreva seu endpoint nos eventos que interessam a você (você pode filtrar por tipo ao configurar o endpoint) e então reaja a eles como a fonte da verdade para resultados assíncronos.

Todo evento é entregue no envelope padrão descrito em Visão geral de webhooks e assinado conforme descrito em Verificando assinaturas. O campo type carrega um dos valores abaixo.

Trate os eventos de forma idempotente. Faça a deduplicação pelo id do evento e, quando um evento alterar um estado importante, reconcilie com a API (por exemplo, GET /api/v1/transactions/:id) antes de agir. Os eventos podem chegar fora de ordem ou mais de uma vez.

Eventos de transação

Event	Quando é disparado
`transaction.created`	Uma transação foi criada e aceita para processamento.
`transaction.pending`	A cobrança está aguardando um resultado assíncrono (por exemplo, PIX, boleto).
`transaction.pre_authorized`	Os fundos foram autorizados, mas não capturados (`capture: false`).
`transaction.authorized`	A cobrança foi bem-sucedida (autorizada e capturada, a menos que seja apenas pré-autorização).
`transaction.capture_pending`	Uma captura foi solicitada e está sendo processada.
`transaction.failed`	A cobrança foi recusada ou não pôde ser concluída.
`transaction.canceled`	A transação foi cancelada antes da conclusão.
`transaction.voided`	Uma autorização foi anulada antes da captura.
`transaction.charged_back`	Um chargeback foi aberto contra a transação.
`transaction.expired`	Uma cobrança pendente expirou sem ser concluída (por exemplo, PIX/boleto não pago a tempo).

Eventos de reembolso

Event	Quando é disparado
`transaction.refund_created`	Um reembolso foi criado.
`transaction.refund_pending`	O reembolso está sendo processado pelo provedor.
`transaction.refunded`	A transação foi totalmente reembolsada.
`transaction.partially_refunded`	Um reembolso parcial foi liquidado; um saldo permanece capturado.
`transaction.refund_failed`	O reembolso não pôde ser concluído.
`transaction.refund_cancelled`	Um reembolso pendente foi cancelado.

Eventos de disputa

Event	Quando é disparado
`transaction.dispute_created`	Uma disputa foi aberta pelo banco do portador do cartão.
`transaction.dispute_updated`	Novas informações ou uma mudança de status em uma disputa aberta.
`transaction.dispute_won`	A disputa foi resolvida a seu favor.
`transaction.dispute_lost`	A disputa foi resolvida contra você.
`transaction.dispute_closed`	A disputa foi encerrada.

Eventos de método de pagamento

Event	Quando é disparado
`payment_method.action_required`	Um método de pagamento armazenado precisa de atenção — por exemplo, um cartão reportado como não mais válido, ou sem substituto disponível pela rede. Solicite ao cliente que o atualize.

Eventos de assinatura

Event	Quando é disparado
`subscription.created`	Uma assinatura foi criada.
`subscription.renewed`	Uma cobrança de renovação foi bem-sucedida e a assinatura avançou para o próximo período.
`subscription.dunning`	Uma cobrança de renovação falhou; a assinatura entrou em cobrança recorrente (retentativas).
`subscription.reactivated`	Uma assinatura voltou a `active` após cobrança recorrente ou uma pausa.
`subscription.upgraded`	A assinatura passou para uma oferta de maior valor.
`subscription.downgraded`	A assinatura passou para uma oferta de menor valor.
`subscription.payment_method_changed`	O instrumento de pagamento da assinatura foi alterado.
`subscription.paused`	A assinatura foi pausada.
`subscription.resumed`	Uma assinatura pausada foi retomada.
`subscription.cancelled`	A assinatura foi cancelada.
`subscription.expired`	A assinatura chegou ao fim de seu prazo e expirou.

Exemplo de payload

Um evento transaction.authorized. O recurso fica em 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"
    }
  }
}

O formato de data.object corresponde ao recurso da API correspondente — uma transação para eventos transaction.*, um reembolso para eventos de reembolso, uma assinatura para eventos subscription.* e assim por diante. Consulte a referência da API para o schema completo de cada objeto.

Orientações de tratamento

Confirme rapidamente. Retorne um 2xx em poucos segundos e faça o trabalho real de forma assíncrona. Respostas lentas ou com falha disparam retentativas.
Faça a deduplicação pelo id. O mesmo evento pode ser entregue mais de uma vez.
Não confie na ordem. Use o próprio status do recurso (ou uma nova leitura da API) em vez de supor que os eventos chegam em sequência.
Verifique cada entrega. Rejeite qualquer requisição cuja assinatura não seja validada — consulte Verificando assinaturas.