Para o negócio: é o webhook que permite liberar o pedido, o acesso ao curso ou o envio do produto assim que o pagamento é confirmado. Sem ele, a confirmação depende de alguém conferir o painel ou de uma rotina que consulta a API de tempos em tempos. Ao contratar a integração, garanta que o time técnico trate os eventos que importam para a sua operação: pagamento confirmado, estorno, bloqueio, falha de assinatura e mudança de status de subconta.
Quando usar
Quando não depender de webhook: na cobrança de cartão, aprovação e recusa voltam na própria resposta de
POST /v1/charges. Use a resposta para decidir o que mostrar ao cliente no checkout e o webhook para manter o seu sistema atualizado depois.
Como funciona
1
Você cadastra um destino
Você cadastra um endpoint de webhook, que é o endereço do seu servidor que recebe os avisos, pelo painel ou pela API. Opcionalmente, cada cobrança pode levar a sua própria URL no campo
postbackUrl.2
Um evento acontece
Por exemplo, o cliente paga o QR Code Pix e a cobrança passa para
paid.3
A Finvia envia um POST
A Finvia faz uma requisição HTTP
POST para cada destino que deve receber o evento, com um corpo JSON (Content-Type: application/json) que descreve o evento e traz o recurso.4
Seu servidor confirma o recebimento
O seu endpoint responde com um status
2xx (de 200 a 299) em até 10 segundos. Qualquer outro resultado conta como falha de entrega: erro de conexão, tempo esgotado, redirecionamento (3xx, que não é seguido), 4xx ou 5xx.5
Sua aplicação processa o evento
Depois de responder, a sua aplicação confere o status na API e executa a regra de negócio: libera o pedido, atualiza o financeiro, envia o e-mail.
Webhook e postback
A Finvia tem dois canais de notificação de cobrança. Eles convivem e podem ser usados juntos.
O
postbackUrl é um canal assíncrono. Ele recebe os eventos da cobrança depois que ela foi criada e não substitui a resposta da criação. O QR Code e a validade do Pix chegam na resposta síncrona de POST /v1/charges.
Quem recebe cada evento
Os eventos de cobrança, de assinatura e de saque são entregues de acordo com a conta dona do recurso. Uma cobrança ou assinatura criada com a chave de uma subconta pertence à subconta. O evento vai para:- Os endpoints cadastrados na conta dona, filtrados por
enabled_events(lista vazia recebe todos). - Os endpoints da conta master (MerchantMaster) cadastrados com a opção de incluir subcontas (
include_submerchants: true), quando a dona é uma subconta. Essa opção só existe para contas master com Connect habilitado. O payload traz omerchant_id(oumerchantId) da subconta, e é assim que a master identifica a origem. - O
postbackUrlda cobrança, se ele foi informado. Assinaturas e saques não têmpostbackUrl.
Configuração
- Pelo painel
- Pela API (endpoints)
- Na cobrança (postback)
1
Selecione a conta
No painel da Finvia, selecione a conta que vai receber os eventos (a master ou uma subconta).
2
Abra a área de webhooks
Vá em Configurações > Webhooks.
3
Informe a URL
Use uma URL pública com HTTPS, por exemplo
https://meusite.com.br/webhooks/finvia. Na conta master com Connect, marque a opção de incluir subcontas se quiser receber também os eventos delas.Eventos por canal
Esta é a tabela de referência de eventos e canais. As demais páginas da documentação apontam para cá.
O que cada evento de cobrança significa:
Quando o charge.updated é enviado
Ocharge.updated é o postback legado. Ele é enviado só ao postbackUrl, nas situações abaixo:
- O adquirente informa uma mudança de status pelo webhook dele: pagamento, recusa ou falha assíncrona, estorno, chargeback.
- O 3DS gerenciado termina em recusa ou falha.
- A cobrança é bloqueada.
- A cobrança recebe um alerta de pré-chargeback.
- Um Pix pago gera
charge.paide tambémcharge.updatednopostbackUrl. - Endpoint de webhook nunca recebe
charge.updated. Incluir esse nome emenabled_eventsnão tem efeito. - O chargeback formalizado chega como
charge.updatedcomstatus: "chargeback"e, quando o valor é revertido do saldo, também comocharge.refunded. Detalhes em Webhooks de cobrança. - A liberação de um bloqueio não gera evento nenhum.
Formato por família
Os formatos dos webhooks variam por família de evento. O formato atual é mantido por compatibilidade com integrações em produção, então escreva o parser seguindo esta tabela.Envelope padrão (cobranças e assinaturas)
Postback legado charge.updated
Não temid de evento nem livemode. O data é a cobrança em camelCase (pspRefId, paymentMethod, isBlocked, isTest). O formato completo está em Webhooks de cobrança.
Envelope de saque
Oid da raiz é o id do saque (o mesmo de data.id), não há livemode e os valores chegam como texto decimal com 8 casas:
Aviso de status de subconta
Chega sem envelope: o corpo é o próprio objeto, commerchantId, status, date e, em rejected e correcting, rejectionReason. Veja Webhooks de conta.
Teste e produção
Os endpoints de webhook não têm modo: cada conta tem uma única lista de endpoints, que recebe os eventos de teste e os de produção. São de teste as cobranças criadas com a chavesk_test_ e as pagas em link de pagamento criado em Modo Teste. O painel não tem uma lista separada de endpoints para o Modo Teste.
Como descartar eventos repetidos
O mesmo evento pode chegar mais de uma vez. Grave a chave de cada evento recebido em um armazenamento persistente (banco de dados ou Redis) e ignore um evento cuja chave já exista. Esta é a regra que funciona com o corpo da mensagem:Regras de negócio
Passo a passo
O seu endpoint precisa:- Aceitar requisições
POSTna URL configurada. - Ler o corpo JSON e identificar a família do evento.
- Responder com status
2xxantes de executar lógica pesada. - Descartar eventos repetidos com a receita de deduplicação.
- Processar o evento de forma assíncrona, confirmando o status na API.
Exemplo em Node.js (Express)
O exemplo grava a chave de deduplicação no banco (idempotência persistente) e usa uma fila simples em memória para processar fora da requisição. Em produção, troque a fila em memória por uma fila do seu ambiente (Redis, SQS, RabbitMQ ou similar), para não perder eventos se o processo reiniciar.Node.js
Exemplo em PHP
PHP
Valide consultando a API
cURL
Entrega e retentativas
Em validação (V-58): esta seção inteira, com retentativas, cabeçalhos
X-Webhook-* e deduplicação pelo cabeçalho, entra no ar junto com o deploy da retentativa automática. A aplicação aos webhooks de saque será confirmada junto com a mudança do webhook de saque (V-16).postbackUrl da cobrança e para a URL de aviso de status de conta.
O que conta como entregue
A notificação é considerada entregue quando o seu servidor responde com status2xx (de 200 a 299) em até 10 segundos. Qualquer outro resultado conta como falha e gera nova tentativa: erro de conexão, falha de DNS, tempo esgotado, redirecionamento (3xx, que não é seguido), 4xx ou 5xx.
Retentativas
- São até 8 tentativas por destino, e a primeira é imediata.
- As seguintes acontecem com intervalos de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas e 24 horas entre uma tentativa e a próxima, cerca de 45 horas no total. Os horários podem variar alguns minutos.
- Se o seu servidor responder
429ou503com o cabeçalhoRetry-After, a próxima tentativa respeita esse prazo, até no máximo 1 hora a mais, sem aumentar o número de tentativas.
429 ou 503 com Retry-After pode alongar a espera até a próxima tentativa, sem aumentar o número de tentativas.
Cabeçalhos enviados
Identificador e duplicidade
A entrega é garantida pelo menos uma vez: em casos raros, a mesma notificação pode chegar mais de uma vez. Responda2xx assim que receber e processe depois.
Use o cabeçalho X-Webhook-Event-Id como chave de deduplicação. Ele é o mesmo em todas as tentativas de uma notificação e no reenvio feito pelo suporte.
Node.js
Ordem
A ordem de entrega não é garantida. Umcharge.paid pode chegar antes do charge.pending da mesma cobrança, por exemplo. Para saber o estado atual, use o status do próprio objeto ou consulte a API (GET /v1/charges/{id}, GET /v1/subscriptions/{id}, GET /v1/submerchants/{merchantId}).
Endpoints com falha
Endpoints com falhas repetidas não são desativados automaticamente. Corrija o destino para que as próximas tentativas sejam bem-sucedidas.Como testar
Ferramentas
Simulador de eventos de teste
POST /v1/charges/{id}/resend-webhook simula um evento para uma cobrança de teste. Você escolhe o status (paid, pending, refused, failed, refunded, in_analysis ou authentication_required) e a rota gera um evento novo charge.{status}, com id novo, para o postbackUrl da cobrança e para os endpoints da própria conta. A cobrança não muda de status.
cURL
- A rota só aceita cobranças de teste. Com uma cobrança de produção, a resposta é
403. - Use-a para testar a conectividade e o tratamento de cada status. O payload simulado tem diferenças em relação ao real (traz campos a mais e não traz
anticipation_fee_estimated), então não o use como referência de schema. - Cada chamada gera um evento com
iddiferente. Duas chamadas com o mesmo status produzem dois eventos distintos, e a deduplicação não descarta o segundo.
Cenários da homologação
A integração está pronta quando o seu endpoint responde
2xx em poucos segundos, separa eventos de teste e de produção, ignora eventos repetidos e só executa ações depois de confirmar o status na API.Erros comuns
Perguntas frequentes
Preciso usar webhook e postback ao mesmo tempo?
Preciso usar webhook e postback ao mesmo tempo?
Não é obrigatório. O endpoint de webhook cobre as cobranças, assinaturas e saques da conta. O postback serve quando você precisa de uma URL diferente por cobrança ou quer receber o
charge.updated (chargeback formalizado, recusas assíncronas), que só chega por esse canal.Como sei que o webhook veio da Finvia?
Como sei que o webhook veio da Finvia?
As mensagens não têm assinatura HMAC. Trate o webhook como um aviso de que algo mudou e confirme o status consultando a API com a sua chave secreta antes de agir.
O QR Code do Pix vem no webhook?
O QR Code do Pix vem no webhook?
O webhook de cobrança Pix traz
payment_details com o código copia e cola e a imagem do QR Code. Para mostrar o QR Code ao cliente, use a resposta de POST /v1/charges, que chega antes de qualquer webhook.Tenho uma lista de endpoints para teste e outra para produção?
Tenho uma lista de endpoints para teste e outra para produção?
Não. A lista é uma só e recebe os dois tipos de evento. Nos eventos de cobrança,
livemode vem false e data.is_test vem true quando a cobrança é de teste. No charge.updated, use data.isTest.Como escolho os eventos que um endpoint recebe?
Como escolho os eventos que um endpoint recebe?
Pela API, no campo
enabled_events de POST /v1/webhook-endpoints ou de PUT /v1/webhook-endpoints/{webhookId}. Lista vazia recebe todos. O painel sempre cadastra o endpoint para todos os eventos.Perdi eventos enquanto meu servidor estava fora. E agora?
Perdi eventos enquanto meu servidor estava fora. E agora?
Consulte os recursos pela API para reconciliar: listagem de cobranças, assinaturas, saques e subcontas. A política de novas tentativas está em Entrega e retentativas.
Veja também
Webhooks de cobrança
Eventos, campos e payloads de cobrança.
Webhooks de assinatura
Ativação, renovação, falha e cancelamento.
Webhooks de saque
Aprovação e rejeição de saques de subcontas.
Webhooks de conta
Status de aprovação das subcontas.
Criar endpoint de webhook
Cadastro pela API, com filtro de eventos.
Catálogo de eventos
Todos os eventos em uma página.

