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
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:Campos Obrigatórios
Campos Obrigatórios
string
obrigatório
Tipo do evento.Valores possíveis:
CashIn, CashOut, CashInReversal, CashOutReversalstring
obrigatório
Status da transação.Valores possíveis:
PENDING, CONFIRMED, ERRORstring
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"Campos de Valores
Campos de Valores
Campos Opcionais
Campos Opcionais
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