Configurar Webhooks
Visão Geral
O cadastro das URLs de webhook é feito exclusivamente pelo painel (https://banking.fypay.me), em Configurações → Webhooks. Não há endpoint de API para cadastrar, listar ou remover webhooks, nem para gerar a chave de assinatura.
Mudanças na configuração de webhooks são aplicadas imediatamente. Eventos subsequentes usarão as URLs configuradas.
Cadastrar um webhook
Entre em https://banking.fypay.me e abra Configurações → Webhooks.
Selecione o tipo de evento que a URL vai receber:
cash_in- PIX recebidocash_out- PIX enviadorefund_in- Estorno de recebimentorefund_out- Devolução recebidamed_created- MED (Mecanismo Especial de Devolução) aberto contra uma transação recebidamed_accepted- Solicitação de devolução MED aprovadamed_rejected- Solicitação de devolução MED rejeitada
Informe a URL do seu endpoint. Ela deve usar HTTPS (HTTP não é aceito) e ser uma URL pública válida (endereços privados ou internos são recusados).
Exemplo: https://api.example.com/webhooks/pix
Cadastre até 5 headers que serão enviados em todo webhook desta URL. Úteis para autenticar a chamada no seu endpoint (por exemplo, Authorization ou X-Webhook-Secret).
- Nome do header: apenas letras, números,
-e_ - Valor do header: não pode ser vazio
- Headers bloqueados:
host,content-length,connection,transfer-encoding,content-type,user-agent
Defina o formato do payload enviado para esta URL nos eventos de transação:
- Padrão (valor default): formato descrito nesta seção de Webhooks
- PIX BACEN: formato da aba PIX BACEN
Os eventos MED usam sempre o mesmo payload, independente da versão.
No mesmo menu, gere a chave de assinatura HMAC. A partir daí, todo webhook traz o header X-Avista-Signature, que você deve validar no seu endpoint. Veja Implementação para o passo a passo de geração, rotação e validação.
Múltiplas URLs por Evento
Você pode cadastrar até 3 URLs HTTPS ativas para o mesmo evento. Cadastrar uma URL nova adiciona essa URL ao evento; as URLs já cadastradas continuam ativas e não são substituídas.
Quando o evento ocorre, a notificação é enviada em fan-out para todas as URLs ativas cadastradas naquele evento. Cada URL possui sua própria entrega e retentativa: uma falha em uma URL não afeta as demais.
Para editar os headers ou a versão de uma URL, ou para removê-la e liberar espaço no limite de 3, use o mesmo menu Configurações → Webhooks.
Configurando Múltiplos Eventos
Para receber notificações de vários tipos de evento, cadastre a URL em cada evento desejado no painel.
Você pode usar a mesma URL para todos os tipos de evento e diferenciar pelo campo event no payload do webhook.
Próximos Passos
Visão Geral
Eventos, autenticação, allowlist de IPs e estrutura do payload
Implementação
Exemplos de código para processar webhooks e validar a assinatura
Reenviar Webhook
Reenvie webhooks perdidos ou para testes
Cash-In Webhook
Detalhes do webhook de PIX recebido
Webhooks MED
Receba notificações sobre eventos MED (Mecanismo Especial de Devolução)