Skip to main content
Esta página lista todas as notificações que a Finvia envia ao seu sistema. Use-a para saber quais eventos tratar, em que destino cada um chega e como reconhecer o formato do corpo. O detalhe de cada família, com payloads completos, está no guia correspondente.
Para o negócio: cada família tem destinos próprios. O charge.updated com o chargeback formalizado, por exemplo, chega só no postbackUrl da cobrança, e o aviso de aprovação de subconta chega só na URL de aviso de status da subconta. Defina com o time técnico quais destinos a operação precisa antes de ir para produção.

Destinos de entrega

Os eventos são roteados pela conta dona do recurso. A regra completa está em Quem recebe cada evento.

Todos os eventos

subscription.trial_started e subscription.trial_ended existem no contrato de tipos, mas não são entregues hoje. Para acompanhar o trial, use subscription.activated e subscription.renewed, que trazem o objeto trial. Não há evento para a liberação de um bloqueio nem para a criação de um saque.
Recusas e falhas informadas depois pelo adquirente (cobrança em análise negada, Pix cancelado ou expirado) geram só o charge.updated no postbackUrl. A cobrança recorrente de assinatura recusada gera subscription.payment_failed e não gera charge.refused. O chargeback formalizado chega como charge.updated com status: "chargeback" e, quando o valor sai do saldo, também como charge.refunded.
O desenho abaixo mostra quais eventos saem da criação da cobrança até o primeiro resultado, e para qual destino vai cada um. O desenho abaixo mostra os eventos que podem chegar depois que a cobrança está paga. O desenho abaixo mostra a ordem dos eventos de assinatura, todos entregues aos endpoints de webhook.

Formato por família

A explicação completa, com exemplos, está em Formato por família.

Envelope padrão (cobrança e assinatura)

Postback legado (charge.updated)

Sem id e sem livemode. O data é a cobrança em camelCase, com isBlocked, blockedAt e blockedReason no bloqueio e, no pré-chargeback, chargebackAlertRefunded e chargebackAlertReason.

Envelope de saque

Sem livemode. O id da raiz é o id da solicitação de saque. Campos em camelCase, valores em texto decimal.

Aviso de status de conta

Sem envelope: o corpo é o próprio objeto da notificação, em camelCase. rejectionReason aparece só em rejected e correcting. date é a data de referência do status.

Confirmação, entrega e deduplicação

  • Confirmação de recebimento: só uma resposta 2xx em até 10 segundos conta como entregue. Redirecionamentos não são seguidos.
  • Entrega e novas tentativas: veja Entrega e retentativas.
  • Deduplicação: o mesmo evento pode chegar mais de uma vez. A chave de cada formato está na receita de deduplicação.
  • Teste e produção: a mesma lista de endpoints recebe os dois. Separe os eventos de cobrança por livemode e is_test (isTest no charge.updated). Saques e avisos de conta não têm marcação de teste.

Segurança

  • Os webhooks não trazem assinatura HMAC: confirme o estado na API antes de uma ação crítica (veja Regras de negócio dos webhooks).
  • Use sempre HTTPS no endpoint.
  • Aplique limite de requisições no seu endpoint.
  • Responda rápido e processe depois: devolva 2xx antes de executar lógica pesada.

Como simular eventos

No sandbox, POST /v1/charges/{id}/resend-webhook gera um evento novo, com id novo, para uma cobrança de teste, com o status que você escolher (paid, pending, refused, failed, refunded, in_analysis ou authentication_required). O evento vai para o postbackUrl da cobrança e para os endpoints da própria conta. O payload simulado não é idêntico ao real, então não o use como referência de schema.

Guias de cada família

Webhooks de cobrança

Payload completo de cada evento charge.* e do charge.updated.

Webhooks de assinatura

Eventos subscription.*, objeto charge e tipos de cancelamento.

Webhooks de saque

payout.approved e payout.rejected das subcontas.

Webhooks de conta

Avisos de aprovação, correção e bloqueio de subcontas.

Veja também

Visão geral de webhooks

Destinos, formatos, entrega e deduplicação.

Status de cobrança

O que cada status significa e o que fazer.