Skip to main content

O que são Webhooks?

Os Webhooks PIX permitem que você receba notificações em tempo real quando o status de uma transação PIX muda. Em vez de fazer polling constantemente na API, seu sistema é notificado automaticamente quando eventos importantes ocorrem.
Webhooks são a forma recomendada de acompanhar o status das transações. Eles reduzem a latência e o consumo de recursos comparado ao polling.

Características

  • Notificações em tempo real
  • Suporte a 4 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out)
  • Retentativas automáticas em caso de falha
  • Autenticação via Basic Auth
  • Payload padronizado em JSON

Eventos Disponíveis

CashIn

Recebimento PIX confirmado (CREDIT)

CashOut

Envio PIX confirmado (DEBIT)

CashInReversal

Estorno de recebimento (DEBIT)

CashOutReversal

Devolução de envio recebida (CREDIT)

Configuração do Endpoint

Para receber webhooks, você precisa:
1

Configurar URL de Webhook

Use a API de Configuração de Webhooks para definir a URL do seu endpoint programaticamente.
2

Implementar Endpoint

Crie um endpoint HTTPS que aceite requisições POST e retorne HTTP 200 rapidamente.
3

Validar Autenticação

Configure a validação do header de autenticação Basic Auth.

Requisitos Técnicos

Se seu endpoint não responder com HTTP 200 dentro de 10 segundos, o webhook será considerado como falha e será retentado.

Autenticação Basic Auth

Os webhooks são enviados com autenticação Basic Auth no header:

Estrutura Base do Payload

Todos os webhooks compartilham uma estrutura base comum:
string
obrigatório
Tipo do evento.Valores possíveis: CashIn, CashOut, CashInReversal, CashOutReversal
string
obrigatório
Status da transação.Valores possíveis: PENDING, CONFIRMED, ERROR
string
obrigatório
Tipo de transação. Sempre PIX para webhooks PIX.
string
obrigatório
Tipo de movimento na conta.
  • CREDIT: Entrada de recursos (recebimento ou devolução recebida)
  • DEBIT: Saída de recursos (envio ou estorno)
string
obrigatório
ID numérico da transação na Fire Banking (retornado como string).Exemplo: "12345"
string
obrigatório
ID End-to-End gerado pelo Banco Central para rastreamento.Exemplo: "E00416968202512111942rjzxxzSSTD9"
string
obrigatório
Data e hora do processamento (ISO 8601 UTC).Exemplo: "2025-12-11T19:42:04.080Z"
number
obrigatório
Taxa cobrada pela transação em reais (BRL).Exemplo: 0.01
number
obrigatório
Valor original da transação em reais (BRL).Exemplo: 0.50
number
obrigatório
Valor final após aplicação de taxas.
  • Para CREDIT: originalAmount - feeAmount
  • Para DEBIT: originalAmount + feeAmount
string
ID externo fornecido na criação da transação.Exemplo: "PIX-5482123298-EJUYFSMU1UU"
string
Chave PIX utilizada na transação (CPF, CNPJ, email, telefone ou chave aleatória).
string
Código de erro quando status é ERROR. Nulo se sucesso.
string
Mensagem de erro descritiva. Nulo se sucesso.
object
Metadados adicionais específicos do evento.

Próximos Passos

Configurar Webhooks

Configure URLs de webhook via API

CashIn

Detalhes do evento de recebimento

CashOut

Detalhes do evento de envio

CashInReversal

Detalhes do evento de estorno

CashOutReversal

Detalhes do evento de devolução