Skip to main content
Um webhook é uma notificação que a Finvia envia ao seu sistema quando algo acontece: um Pix foi pago, um estorno foi concluído, uma assinatura renovou, um saque foi aprovado. Com webhooks, a sua aplicação fica sabendo da mudança logo depois que ela acontece, sem precisar consultar a API repetidamente para descobrir se o status mudou (prática chamada de polling).
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.
Se a mesma URL estiver cadastrada como endpoint e também for enviada como postbackUrl, ela recebe cada evento de cobrança duas vezes. Use URLs diferentes ou deixe a deduplicação cuidar da repetição.

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:
  1. Os endpoints cadastrados na conta dona, filtrados por enabled_events (lista vazia recebe todos).
  2. 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 o merchant_id (ou merchantId) da subconta, e é assim que a master identifica a origem.
  3. O postbackUrl da cobrança, se ele foi informado. Assinaturas e saques não têm postbackUrl.
Sem nenhum desses destinos, ninguém recebe o evento. Endpoints da master sem a opção de incluir subcontas não recebem eventos das subcontas. O desenho abaixo mostra como a Finvia escolhe os destinos de cada evento.

Configuração

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.
O painel não tem seleção de eventos: o endpoint cadastrado por ele recebe todos os eventos (cobrança, assinatura e saque).
O aviso de status de conta tem configuração própria, explicada em Webhooks de conta.

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:
Recusas e falhas informadas depois pelo adquirente (uma cobrança que ficou em in_analysis e termina negada, um Pix cancelado ou expirado) não geram charge.refused nem charge.failed. Nesses casos sai só o charge.updated no postbackUrl. Para cobranças que ficam em in_analysis ou pending, acompanhe pelo postbackUrl ou consulte GET /v1/charges/{id}.

Quando o charge.updated é enviado

O charge.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.
Consequências práticas:
  • Um Pix pago gera charge.paid e também charge.updated no postbackUrl.
  • Endpoint de webhook nunca recebe charge.updated. Incluir esse nome em enabled_events não tem efeito.
  • O chargeback formalizado chega como charge.updated com status: "chargeback" e, quando o valor é revertido do saldo, também como charge.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.
Para o desenvolvedor: no charge.updated, use só os campos documentados. Ele traz campos a mais, que podem mudar sem aviso. Se você depende de uma chave de metadata, envie-a em camelCase (orderId): ela chega igual nos dois formatos. Veja Metadata.

Envelope padrão (cobranças e assinaturas)

Postback legado charge.updated

Não tem id 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

O id 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, com merchantId, status, date e, em rejected e correcting, rejectionReason. Veja Webhooks de conta.
Um parser que espera snake_case quebra no charge.updated, e um que espera event quebra no aviso de conta. Identifique a família antes de ler os campos: há event? Ele começa com charge., subscription. ou payout.? É charge.updated?

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 chave sk_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.
O endpoint usado na homologação continua recebendo eventos de teste depois que você entra em produção. Descarte ou separe os eventos de cobrança com livemode: false antes de liberar pedidos. Para ter URLs diferentes por ambiente, use o postbackUrl, que é definido em cada cobrança.

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:
Para o desenvolvedor: trate o charge.updated e o aviso de conta como atualização de estado. Gravar o mesmo estado duas vezes deixa o registro igual. Use a chave para não repetir efeitos colaterais, como e-mails ao cliente. Quando a entrega com retentativa entrar no ar, use o cabeçalho descrito em Identificador e duplicidade.

Regras de negócio

Não libere produto, acesso ou saldo só com base no corpo do webhook. Como não há assinatura HMAC, qualquer pessoa que descubra a sua URL consegue enviar um POST com aparência de evento. Antes de uma ação crítica, consulte o recurso na API (por exemplo, GET /v1/charges/{id}) e use o status que a API devolver.

Passo a passo

O seu endpoint precisa:
  1. Aceitar requisições POST na URL configurada.
  2. Ler o corpo JSON e identificar a família do evento.
  3. Responder com status 2xx antes de executar lógica pesada.
  4. Descartar eventos repetidos com a receita de deduplicação.
  5. Processar o evento de forma assíncrona, confirmando o status na API.
O desenho abaixo mostra o receptor recomendado: responder rápido, descartar repetidos e confirmar na API antes de agir.

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
Se o status devolvido pela API não confirmar o evento, não execute a ação e registre o caso para análise.

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).
A política abaixo vale para os endpoints de webhook, para o 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 status 2xx (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 429 ou 503 com o cabeçalho Retry-After, a próxima tentativa respeita esse prazo, até no máximo 1 hora a mais, sem aumentar o número de tentativas.
Depois da última tentativa, a notificação fica registrada como não entregue e pode ser reenviada mediante solicitação ao suporte. O reenvio usa o mesmo identificador do evento. O desenho abaixo mostra a sequência de tentativas que entra no ar com o deploy da retentativa (V-58). Uma resposta 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. Responda 2xx 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. Um charge.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 id diferente. 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

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.
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 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.
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.
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.
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.