> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks: visão geral

> Receba no seu sistema os avisos de pagamento, estorno, bloqueio, assinatura, saque e conta, e saiba quem recebe cada evento e em que formato.

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

> [!NOTE]
>
> **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

| Situação | O que o webhook resolve |
| - | - |
| Venda por Pix | O cliente paga minutos depois da criação da cobrança. O evento `charge.paid` avisa o momento exato |
| Assinatura | A renovação acontece sem ninguém na tela. Os eventos `subscription.*` avisam renovação, falha e cancelamento |
| Estorno e disputas | `charge.refunded`, `charge.pre_chargeback` e `charge.blocked` avisam estorno, alerta de pré-chargeback e bloqueio. O postback `charge.updated` avisa o chargeback formalizado |
| Marketplace com Connect | Os eventos `payout.*` e o aviso de status de conta informam saques e aprovação das subcontas |

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.

| | Webhook (endpoints) | Postback (`postbackUrl`) |
| - | - | - |
| Onde se configura | No painel ou em [`POST /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint), uma vez, para a conta | No corpo de cada `POST /v1/charges` |
| Abrangência | Cobranças, assinaturas e saques da conta dona do endpoint | Somente a cobrança em que a URL foi informada |
| Filtro de eventos | Pela API, com `enabled_events`. O endpoint cadastrado pelo painel recebe todos os eventos | Não há filtro: recebe todos os eventos de cobrança |
| Eventos | Envelope padrão de cobrança, assinatura e saque | Os mesmos eventos de cobrança dos endpoints, mais o `charge.updated` legado |
| Uso típico | Integração principal do sistema | Plataformas que precisam de uma URL diferente por pedido ou por cliente, e quem precisa do `charge.updated` |

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

> [!WARNING]
>
> 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](#como-descartar-eventos-repetidos) 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.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    EV(["Um evento acontece<br/>cobrança, assinatura ou saque"]):::neutro
    DONA["Conta dona do recurso<br/>quem criou com a chave dela"]:::finvia
    SQ{"Saque da master ou<br/>de conta sem Connect?"}:::decisao
    NADA["Não gera webhook<br/>acompanhe pela<br/>listagem de saques"]:::neutro
    E1["Endpoints da conta dona<br/>filtrados por enabled_events<br/>lista vazia recebe todos"]:::lojista
    SUB{"A dona é<br/>uma subconta?"}:::decisao
    E2["Endpoints da master com<br/>include_submerchants: true<br/>merchant_id indica a subconta"]:::lojista
    PB{"Cobrança com<br/>postbackUrl?"}:::decisao
    E3["postbackUrl da cobrança<br/>mesmos eventos de cobrança<br/>e também o charge.updated"]:::lojista
    EV --> DONA --> SQ
    SQ -->|"sim"| NADA
    SQ -->|"não"| E1
    DONA --> SUB
    SUB -->|"sim"| E2
    DONA --> PB
    PB -->|"sim"| E3
    ST(["Mudança de status<br/>de uma subconta"]):::neutro
    E4["Só a URL de aviso de<br/>status da subconta<br/>sem envelope"]:::lojista
    ST --> E4
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

| Caso | Quem recebe |
| - | - |
| Cobrança da master com split para uma subconta | Só os destinos da master. A subconta que apenas participa do split não recebe o evento da cobrança |
| Cobrança criada com a chave da subconta | Endpoints da subconta, endpoints da master com `include_submerchants: true` e o `postbackUrl` da cobrança |
| Saque de subconta (`payout.*`) | Endpoints da subconta e endpoints da master com `include_submerchants: true` |
| Saque da própria conta (master ou conta sem Connect) | Ninguém: não gera webhook. Acompanhe pela [listagem de saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) |
| Mudança de status de subconta | Só a URL de aviso de status da subconta. Veja [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md) |

## Configuração

> [tab] Pelo painel
>
> **1. Selecione a conta**
>
> No [painel da Finvia](https://app.finvia.com.br), 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).

> [tab] Pela API (endpoints)
>
> Use a rota [`POST /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint), com o id da conta em `merchantId` na query e o corpo em snake\_case. A API permite escolher os eventos em `enabled_events`.
>
> ```bash cURL theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD" \
>   -u "$FINVIA_API_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "url": "https://meusite.com.br/webhooks/finvia",
>     "enabled_events": ["charge.paid", "charge.refunded", "charge.blocked"],
>     "include_submerchants": true
>   }'
> ```
>
> A resposta é `201` sem corpo. Para saber o id do endpoint criado, use [`GET /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/listar-endpoints).

> [tab] Na cobrança (postback)
>
> Informe `postbackUrl` na criação da cobrança:
>
> ```json theme={null}
> {
>   "amount": 100,
>   "currency": "BRL",
>   "customer": { "name": "Joao Silva", "email": "joao@email.com" },
>   "paymentMethod": { "type": "pix", "expirationInDays": 1 },
>   "items": [
>     { "title": "Produto XYZ", "type": "digital", "description": "Descrição do produto", "unit_price": 100, "quantity": 1 }
>   ],
>   "postbackUrl": "https://meusite.com.br/webhooks/finvia"
> }
> ```

O aviso de status de conta tem configuração própria, explicada em [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md).

## Eventos por canal

Esta é a tabela de referência de eventos e canais. As demais páginas da documentação apontam para cá.

| Evento | Endpoints da conta dona | Endpoints da master com `include_submerchants` | `postbackUrl` da cobrança | Formato |
| - | - | - | - | - |
| `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback`, `charge.blocked` | Sim | Sim, para cobranças de subconta | Sim | Envelope padrão |
| `charge.updated` | **Não** | **Não** | Sim | Legado, sem `id` e sem `livemode`, camelCase |
| `subscription.created`, `subscription.activated`, `subscription.renewed`, `subscription.payment_failed`, `subscription.cancelled`, `subscription.expired` | Sim | Sim, para assinaturas de subconta | Não se aplica | Envelope padrão |
| `payout.approved`, `payout.rejected` | Sim, só para saques de subconta | Sim | Não se aplica | Envelope de saque |
| Aviso de status de subconta | Não | Não | Não | Sem envelope. Vai para a URL de aviso de status da subconta |

O que cada evento de cobrança significa:

| Evento | Quando é enviado |
| - | - |
| `charge.created` | A cobrança foi criada. Uma cobrança que fica em `in_analysis` ou `authentication_required` na criação gera só este evento até o desfecho |
| `charge.pending` | O processamento terminou em `pending` (por exemplo, Pix com QR Code gerado) |
| `charge.paid` | O pagamento foi confirmado, na hora ou depois, pelo adquirente |
| `charge.refused`, `charge.failed` | A cobrança foi recusada (`refused`) ou falhou (`failed`) na criação ou ao final do 3DS gerenciado |
| `charge.refunded` | O estorno foi concluído |
| `charge.pre_chargeback` | Um alerta de pré-chargeback foi registrado |
| `charge.blocked` | A cobrança foi bloqueada (por exemplo, por MED ou chargeback em análise) |

> [!WARNING]
>
> 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](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md#chargeback-formalizado).
* 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.

| Família | Envelope | Chaves de `data` | Exceções |
| - | - | - | - |
| Cobrança: `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback`, `charge.blocked` | `{ id, event, livemode, data }` | snake\_case no primeiro nível (`psp_ref_id`, `merchant_id`, `payment_details`, `is_test`, `anticipation_fee_estimated`) | Os objetos aninhados mantêm o formato em que foram gravados, em camelCase: `payment_method` de cartão, `shipping_address`, `tracking_info`, `three_ds`, `freight_details` e `payment_details` do Pix. `metadata` volta exatamente como você enviou |
| Cobrança legada: `charge.updated` | `{ event, data }`, sem `id` e sem `livemode` | camelCase em todos os níveis (`pspRefId`, `isBlocked`, `isTest`) | As chaves de `metadata` também são convertidas para camelCase (veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata)). Traz mais campos que o envelope padrão |
| Assinatura: `subscription.*` | `{ id, event, livemode, data }` | snake\_case (`merchant_id`, `current_period_end`, `charge.charge_id`, `failure_reason`) | O objeto `trial` usa camelCase (`startDate`, `endDate`, `convertedAt`). `metadata` volta como foi enviada |
| Saque: `payout.*` | `{ id, event, data }`, sem `livemode` | camelCase | O `id` da raiz é o id do saque e se repete nos eventos do mesmo saque. `amount`, `payoutFee` e `netAmount` chegam como texto decimal |
| Aviso de status de conta | Sem envelope | camelCase (`merchantId`, `status`, `date`, `rejectionReason`) | Não tem nome de evento |
| Respostas da API REST | Não se aplica | camelCase | Em `GET /v1/charges/{id}`, as chaves de `metadata` voltam em camelCase |

> [!TIP]
>
> **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](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata).

### Envelope padrão (cobranças e assinaturas)

```json theme={null}
{
  "id": "evt_1XcN7hJ4uQ2pZ8eL6wS3kF9a",
  "event": "charge.paid",
  "livemode": true,
  "data": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "status": "paid",
    "merchant_id": "3Fq9TzL2mWc8VbN1xR7pK4hJ6sD",
    "is_test": false
  }
}
```

| Campo | O que é |
| - | - |
| `id` | Identificador do evento. Trate como texto opaco |
| `event` | Nome do evento, como `charge.paid` ou `subscription.renewed` |
| `livemode` | Nos eventos de cobrança, `false` indica cobrança de teste (`data.is_test: true`) |
| `data` | O objeto do recurso (a cobrança ou a assinatura). O exemplo acima foi resumido |

### 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](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md#postback-legado).

### 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:

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "event": "payout.approved",
  "data": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "amount": "100.00000000",
    "currency": "BRL",
    "status": "approved",
    "payoutFee": "1.00000000",
    "netAmount": "99.00000000"
  }
}
```

### 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](https://docs.fastpaybrasil.com/guias/webhooks/conta.md).

> [!WARNING]
>
> 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.

| Família | Como reconhecer um evento de teste |
| - | - |
| Cobrança, envelope padrão | `livemode: false` e `data.is_test: true` |
| `charge.updated` | `data.isTest: true` |
| Assinatura | Não use `livemode` para separar teste de produção. As assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste |
| Saque e aviso de conta | Não têm marcação de teste |

> [!WARNING]
>
> 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:

| Mensagem | Chave de deduplicação | Por quê |
| - | - | - |
| Envelope padrão (`charge.*` exceto `charge.updated`, e `subscription.*`) | `id` do envelope | É o identificador do evento |
| `charge.updated` | `event` + `data.id` + `data.status` + `data.isBlocked` + `data.chargebackAlertRefunded` + `data.updatedAt` (os três últimos quando presentes) | Não há `id` de evento. O bloqueio mantém o `status` `paid` e muda só `isBlocked`. O alerta de pré-chargeback se distingue por `chargebackAlertRefunded`. O `updatedAt` muda a cada atualização da cobrança |
| Saque (`payout.*`) | `id` da raiz + `event` | O `id` é o do saque e se repete nos eventos do mesmo saque. Cada saque gera no máximo um `payout.approved` ou um `payout.rejected` |
| Aviso de status de subconta | Compare o `status` recebido com o último status gravado para aquela subconta. Se for igual, ignore | Não há envelope nem id. O campo `date` é a data de referência do status e pode se repetir: no desbloqueio, o aviso `active` traz a data original de aprovação |

> [!TIP]
>
> **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](#identificador-e-duplicidade).

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Confirmação de recebimento | Só uma resposta `2xx` em até 10 segundos conta como entregue. Redirecionamentos não são seguidos |
| Entrega repetida | O mesmo evento pode chegar mais de uma vez. Use a [receita de deduplicação](#como-descartar-eventos-repetidos) |
| Sem assinatura HMAC | As mensagens não trazem cabeçalho de assinatura. Confirme os dados na API antes de ações críticas |
| HTTPS | Use sempre HTTPS na URL de recebimento. Endereços internos e reservados não são aceitos no cadastro do endpoint |
| Filtro de eventos | `enabled_events` só existe pela API e vale só para endpoints. Lista vazia recebe todos |
| Teste e produção | A mesma lista de endpoints recebe os dois. Separe por `livemode` e `is_test` |

> [!WARNING]
>
> 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](#como-descartar-eventos-repetidos).
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.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
sequenceDiagram
    autonumber
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(243,245,248) Sua aplicação
        participant R as Seu endpoint
        participant DB as Banco de chaves
        participant Q as Fila e worker
    end
    F->>R: POST com o evento em JSON
    R->>R: Identifica a família do evento
    R->>DB: Grava a chave de deduplicação
    alt Chave nova
        DB-->>R: Gravada
        R-->>F: 2xx em até 10 segundos
        R-)Q: Enfileira o evento
        Q->>F: GET /v1/charges/{id}
        F-->>Q: Status atual da cobrança
        Note over Q: Libera o pedido só se a API confirmar o status
    else Chave já existe
        DB-->>R: Já recebido
        R-->>F: 2xx, sem processar de novo
    end
    Note over R,DB: Envelope padrão usa o id do evento como chave. Saque, charge.updated e aviso de conta têm receita própria
```

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

```javascript Node.js theme={null}
// webhook.mjs (Node.js 18+, ESM)
import express from 'express';
import db from './db.js'; // seu módulo de banco; tabela webhook_events (event_key TEXT PRIMARY KEY, received_at TIMESTAMP)

const API_URL = 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const app = express();
app.use(express.json());

// Receita de deduplicação pelo corpo (veja "Como descartar eventos repetidos").
// Devolve null para o aviso de conta, que é tratado por comparação de status.
function dedupKey(body) {
  const event = body.event ?? '';
  if (event.startsWith('payout.')) return `payout:${body.id}:${event}`;
  if (event === 'charge.updated') {
    const d = body.data ?? {};
    return ['charge.updated', d.id, d.status, d.isBlocked ?? '', d.chargebackAlertRefunded ?? '', d.updatedAt ?? ''].join(':');
  }
  if (event && body.id) return `evt:${body.id}`;
  return null;
}

// Fila simples em memória (exemplo). Em produção, use uma fila persistente.
const queue = [];
let working = false;

async function runQueue() {
  if (working) return;
  working = true;
  while (queue.length) {
    const evt = queue.shift();
    try {
      await handleEvent(evt);
    } catch (err) {
      console.error('Falha ao processar evento', evt.event ?? 'conta', err);
      // Registre para reprocessar depois
    }
  }
  working = false;
}

async function getCharge(id) {
  const res = await fetch(`${API_URL}/v1/charges/${id}`, {
    headers: { Authorization: `Basic ${credentials}` },
  });
  return res.json();
}

async function handleEvent(body) {
  if (!body.event) {
    // Aviso de status de conta: aplique só se o status mudou
    const atual = await db.sellers.getStatus(body.merchantId);
    if (atual !== body.status) await db.sellers.setStatus(body.merchantId, body.status, body.rejectionReason);
    return;
  }
  if (body.event === 'charge.paid' && body.livemode === true) {
    // Confirma na API antes de liberar
    const charge = await getCharge(body.data.id);
    if (charge.status === 'paid') {
      await db.orders.markPaid(body.data.id);
    }
  }
  // Trate as demais famílias aqui
}

app.post('/webhooks/finvia', async (req, res) => {
  const body = req.body;
  const key = dedupKey(body);

  const inserted = key
    ? await db.query(
        'INSERT INTO webhook_events (event_key, received_at) VALUES ($1, NOW()) ON CONFLICT DO NOTHING',
        [key]
      )
    : { rowCount: 1 };

  // Responde rápido, mesmo para eventos repetidos
  res.status(200).send('OK');

  if (inserted.rowCount === 0) return; // já recebido
  queue.push(body);
  runQueue();
});

app.listen(3000);
```

### Exemplo em PHP

```php PHP theme={null}
<?php
// webhook.php
$payload = file_get_contents('php://input');
$body = json_decode($payload, true);

if (!is_array($body)) {
    http_response_code(400);
    exit;
}

$pdo = new PDO(getenv('DATABASE_DSN'));

// Receita de deduplicação pelo corpo (veja "Como descartar eventos repetidos")
$event = $body['event'] ?? '';
if (str_starts_with($event, 'payout.')) {
    $key = 'payout:' . $body['id'] . ':' . $event;
} elseif ($event === 'charge.updated') {
    $d = $body['data'] ?? [];
    $key = implode(':', [
        'charge.updated',
        $d['id'] ?? '',
        $d['status'] ?? '',
        var_export($d['isBlocked'] ?? null, true),
        var_export($d['chargebackAlertRefunded'] ?? null, true),
        $d['updatedAt'] ?? '',
    ]);
} elseif ($event !== '' && isset($body['id'])) {
    $key = 'evt:' . $body['id'];
} else {
    // Aviso de status de conta: sem chave. O worker compara o status recebido
    // com o último gravado para a subconta e ignora se for igual.
    $key = 'conta:' . bin2hex(random_bytes(8));
}

// Idempotência persistente: grava a chave; se já existir, não processa de novo
$stmt = $pdo->prepare('INSERT INTO webhook_events (event_key, payload, status) VALUES (?, ?, ?) ON CONFLICT DO NOTHING');
$stmt->execute([$key, $payload, 'pending']);
$isNew = $stmt->rowCount() > 0;

// Responde rápido
http_response_code(200);
echo 'OK';

// Libera a conexão com a Finvia antes de processar (PHP-FPM)
if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

if ($isNew) {
    // Uma rotina agendada (cron ou worker) lê os registros 'pending',
    // confirma o status na API e executa a regra de negócio.
}
```

### Valide consultando a API

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/charges/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:"
```

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

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    INI(["Evento a entregar<br/>regra após o deploy (V-58)"]):::neutro
    G1["Tentativa 1: imediata<br/>Tentativa 2: 1 min depois<br/>Tentativa 3: 5 min depois"]:::alerta
    G2["Tentativa 4: 30 min depois<br/>Tentativa 5: 2 h depois<br/>Tentativa 6: 6 h depois"]:::alerta
    G3["Tentativa 7: 12 h depois<br/>Tentativa 8: 24 h depois<br/>cerca de 45 h no total"]:::alerta
    OK(["Entregue<br/>2xx em até 10 s<br/>encerra as tentativas"]):::ok
    FIM["Não entregue<br/>reenvio pelo suporte,<br/>com o mesmo id de evento"]:::erro
    INI --> G1
    G1 -->|"falhou"| G2
    G2 -->|"falhou"| G3
    G3 -->|"falhou"| FIM
    G1 -.->|"2xx"| OK
    G2 -.->|"2xx"| OK
    G3 -.->|"2xx"| OK
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

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

| Cabeçalho | Conteúdo |
| - | - |
| `X-Webhook-Event-Id` | Identificador do evento, igual em todas as tentativas |
| `X-Webhook-Delivery-Id` | Identificador da entrega para aquele destino |
| `X-Webhook-Attempt` | Número da tentativa (`1` a `8`; reenvios manuais terminam em `-manual`) |
| `X-Webhook-Event` | Nome do evento |

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

| Mensagem | Chave com o cabeçalho | Correspondência no corpo |
| - | - | - |
| Cobrança e assinatura (envelope padrão) | `X-Webhook-Event-Id` | O mesmo valor está no campo `id` do corpo |
| Saque (`payout.*`) | `X-Webhook-Event-Id` | Nenhuma: o `id` do corpo é o id do saque |
| `charge.updated` | `X-Webhook-Event-Id` | Nenhuma: o corpo não tem `id`. Sem o cabeçalho, use a combinação de campos da [receita pelo corpo](#como-descartar-eventos-repetidos) |
| Aviso de status de conta | `X-Webhook-Event-Id` | Nenhuma: o corpo não tem `id` |

```javascript Node.js theme={null}
// Prefira o cabeçalho; sem ele, caia na receita pelo corpo
const key = req.get('X-Webhook-Event-Id') ?? dedupKey(req.body);
```

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

| Ferramenta | Para que serve |
| - | - |
| ngrok | Expor o seu servidor local na internet durante o desenvolvimento |
| webhook.site | Ver o corpo exato que a Finvia envia, sem escrever código |
| Postman | Enviar manualmente um payload de exemplo para o seu endpoint |

```bash theme={null}
# Instalar o ngrok
npm install -g ngrok

# Expor a porta local
ngrok http 3000

# Use a URL gerada (ex.: https://abc123.ngrok.io/webhooks/finvia) no endpoint ou no postbackUrl
```

### Simulador de eventos de teste

[`POST /v1/charges/{id}/resend-webhook`](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste) 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.

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'
```

* 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

| Código | Cenário |
| - | - |
| CHG-03 | Receber `charge.refused` (ou `charge.failed`) de uma recusa de cartão |
| CHG-04 e CHG-05 | Receber `charge.pending` e `charge.paid` de um Pix |
| CHG-07 | Receber `charge.refunded` após estorno |
| CHG-08 | Receber um webhook e responder `2xx` em poucos segundos |
| CHG-09 | Simular um evento no sandbox com o `resend-webhook` |
| SUB-05 | Receber `subscription.created` e `subscription.activated` |
| FC-08 | Receber o aviso de mudança de status de subconta |

> [!TIP]
>
> 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

| Sintoma | Causa | Como resolver |
| - | - | - |
| Nenhum webhook chega | URL incorreta, fora do ar ou inacessível pela internet (ex.: `localhost`) | Confira a URL do endpoint e teste com cURL de fora da sua rede |
| Entrega contada como falha com o servidor no ar | O endpoint responde `3xx`, `4xx` ou `5xx`, ou demora mais de 10 segundos | Responda `2xx` primeiro e processe depois. Não use redirecionamento na URL |
| O mesmo evento chega duas vezes ao mesmo tempo | A URL está cadastrada como endpoint e também enviada como `postbackUrl` | Use URLs diferentes ou deduplique |
| `charge.updated` não chega nos endpoints | Esse evento vai só para o `postbackUrl` da cobrança | Informe `postbackUrl` nas cobranças |
| A master não recebe eventos das subcontas | O endpoint da master não tem `include_submerchants: true` | Ative a opção no endpoint da master, pelo painel ou pela API |
| A subconta não recebe o evento de uma venda com split | O evento vai só para a conta dona da cobrança | Trate o evento nos destinos da conta dona da cobrança |
| Eventos de teste liberando pedidos em produção | A lista de endpoints é a mesma nos dois ambientes | Descarte eventos de cobrança com `livemode: false` |
| Parser quebra em alguns eventos | Diferença de formato (snake\_case, camelCase, sem envelope) | Siga a tabela de [formato por família](#formato-por-família) |

## Perguntas frequentes

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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`.

> [accordion] Como escolho os eventos que um endpoint recebe?
>
> Pela API, no campo `enabled_events` de [`POST /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint) ou de [`PUT /v1/webhook-endpoints/{webhookId}`](https://docs.fastpaybrasil.com/referencia/webhooks/atualizar-endpoint). Lista vazia recebe todos. O painel sempre cadastra o endpoint para todos os eventos.

> [accordion] Perdi eventos enquanto meu servidor estava fora. E agora?
>
> Consulte os recursos pela API para reconciliar: [listagem de cobranças](https://docs.fastpaybrasil.com/referencia/cobrancas/listar.md), [assinaturas](https://docs.fastpaybrasil.com/referencia/assinaturas/listar.md), [saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) e [subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md). A política de novas tentativas está em [Entrega e retentativas](#entrega-e-retentativas).

## Veja também

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Eventos, campos e payloads de cobrança.

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Ativação, renovação, falha e cancelamento.

> [card] [Webhooks de saque](https://docs.fastpaybrasil.com/guias/webhooks/saque.md)
>
> Aprovação e rejeição de saques de subcontas.

> [card] [Webhooks de conta](https://docs.fastpaybrasil.com/guias/webhooks/conta.md)
>
> Status de aprovação das subcontas.

> [card] [Criar endpoint de webhook](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint.md)
>
> Cadastro pela API, com filtro de eventos.

> [card] [Catálogo de eventos](https://docs.fastpaybrasil.com/anexos/catalogo-de-eventos.md)
>
> Todos os eventos em uma página.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.