Visão Geral
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, enviadas via
POSTcom corpo JSON - 7 tipos de eventos (Cash In, Cash Out, Refund In, Refund Out, MED Created, MED Accepted, MED Rejected)
- Até 3 URLs HTTPS por evento, com entrega para todas elas (fan-out)
- Até 5 headers customizados por URL (por exemplo, um
Authorizationpróprio) - Assinatura HMAC-SHA256 do corpo no header
X-Avista-Signature - Retentativas automáticas em caso de falha e reenvio manual via API
Eventos Disponíveis
CashIn
Recebimento PIX (CREDIT)
CashOut
Envio PIX (DEBIT)
CashInReversal
Estorno de recebimento (DEBIT)
CashOutReversal
Devolução de envio recebida (CREDIT)
MedCreated
MED (Mecanismo Especial de Devolução) aberto contra transação
MedAccepted
Devolução MED aprovada
MedRejected
Devolução MED rejeitada
| Evento | eventType (cadastro) | event (payload) | movementType | Descrição |
|---|---|---|---|---|
| PIX In | cash_in | CashIn | CREDIT | Recebimento PIX |
| PIX Out | cash_out | CashOut | DEBIT | Envio PIX |
| Refund In | refund_in | CashInReversal | DEBIT | Estorno de um recebimento |
| Refund Out | refund_out | CashOutReversal | CREDIT | Devolução recebida de um envio |
| MED Created | med_created | MedCreated | — | MED aberto contra uma transação |
| MED Accepted | med_accepted | MedAccepted | — | Devolução MED aprovada |
| MED Rejected | med_rejected | MedRejected | — | Devolução MED rejeitada |
O cadastro de URLs usa o eventType em snake_case (cash_in, cash_out...). O campo event do payload recebido usa PascalCase (CashIn, CashOut...).
Configuração do Endpoint
Para receber webhooks, você precisa:
Use o painel (https://banking.fypay.me), em Configurações → Webhooks (veja Configurar Webhooks). Você pode cadastrar até 3 URLs HTTPS ativas por evento; no disparo, a notificação é enviada para todas elas (fan-out).
Crie um endpoint HTTPS que aceite requisições POST e responda com um status 2xx em até 10 segundos.
Gere a chave de assinatura no painel e valide o header X-Avista-Signature (veja Implementação). Opcionalmente, valide também os headers customizados que você cadastrou e restrinja os IPs de origem.
Requisitos Técnicos
| Requisito | Descrição |
|---|---|
| Protocolo | HTTPS obrigatório no cadastro |
| Método | POST |
| Content-Type | application/json |
| Timeout | 10 segundos |
| Resposta | Qualquer status 2xx. Redirecionamentos (3xx) não são seguidos e contam como falha |
Se o seu endpoint não responder com 2xx em até 10 segundos, a entrega é considerada falha e será retentada após 30 s, 1 min, 3 min, 5 min e 15 min. Quando há múltiplas URLs cadastradas para o mesmo evento, cada URL tem sua própria entrega: uma falha em uma URL não afeta as demais, e uma URL que já recebeu com sucesso não recebe de novo nas retentativas.
Autenticação dos Webhooks
A FyPay oferece três mecanismos, que podem ser combinados:
| Mecanismo | Como funciona |
|---|---|
| Assinatura HMAC (recomendado) | Depois que você gera a chave de assinatura no painel, todo webhook passa a trazer o header X-Avista-Signature com o HMAC-SHA256 (hex) do corpo bruto. Veja como validar. |
| Headers customizados | Você pode cadastrar até 5 headers por URL (por exemplo, Authorization: Basic ... ou X-Webhook-Secret: ...). Eles são enviados em todo webhook daquela URL e seu endpoint valida os valores. |
| Allowlist de IPs | Aceite apenas requisições vindas dos IPs de origem da FyPay (lista abaixo). |
O nome do header de assinatura é mesmo X-Avista-Signature. Esse é o nome técnico enviado hoje em todos os webhooks assinados; use-o exatamente assim no seu validador.
Enquanto a chave de assinatura não for gerada no painel, os webhooks são entregues sem o header X-Avista-Signature. A FyPay não envia Basic Auth por conta própria: se o seu endpoint exige Authorization, cadastre esse header como header customizado.
Exemplo de validação de um header customizado Authorization: Basic ... que você cadastrou:
app.post('/webhooks/pix', (req, res) => {
const expected = 'Basic ' + Buffer.from(
`${process.env.WEBHOOK_USER}:${process.env.WEBHOOK_PASS}`
).toString('base64');
if (req.headers.authorization !== expected) {
return res.status(401).send('Unauthorized');
}
res.status(200).json({ acknowledged: true });
});Allowlist de IPs
Os webhooks da FyPay saem dos seguintes endereços IP. Se o seu firewall ou WAF restringe tráfego de entrada, libere todos eles:
| IP de origem |
|---|
184.197.16.190 |
54.85.39.76 |
184.197.130.162 |
184.196.180.161 |
52.0.159.232 |
54.88.75.254 |
Libere a lista inteira: o envio pode sair de qualquer um desses IPs. A allowlist complementa a validação da assinatura, mas não a substitui.
Estrutura Base do Payload
Os eventos de transação (CashIn, CashOut, CashInReversal, CashOutReversal) compartilham a estrutura base abaixo. Os eventos MED têm um payload próprio, descrito em MedCreated.
{
"event": "CashIn",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "CREDIT",
"transactionId": "12345",
"externalId": "PIX-5482123298-EJUYFSMU1UU",
"endToEndId": "E00416968202512111942rjzxxzSSTD9",
"pixKey": "1ff6ce09-4244-44d5-aa8f-1fe69f8986a9",
"feeAmount": 0.01,
"originalAmount": 0.5,
"finalAmount": 0.49,
"mismatchAmount": null,
"processingDate": "2025-12-11T19:42:04.080Z",
"errorCode": null,
"errorMessage": null,
"providerId": "a1b2c3d4e5",
"metadata": {}
}Valores monetários são enviados em reais (BRL), com até 5 casas decimais.
Além da base, CashIn e CashOut trazem o objeto counterpart, e CashInReversal e CashOutReversal trazem o objeto parentTransaction.
Próximos Passos
Configurar Webhooks
Configure URLs de webhook via API
Implementação
Validação da assinatura, idempotência e retentativas
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
MedCreated
Detalhes do evento de abertura de MED
MedAccepted
Detalhes do evento de MED aprovado
MedRejected
Detalhes do evento de MED rejeitado