Meu webhook não está recebendo as notificações
O webhook é o aviso automático que mandamos ao seu sistema quando um pagamento é confirmado. Quando ele para de chegar, é quase sempre um de...
O webhook é o aviso automático que mandamos ao seu sistema quando um pagamento é confirmado. Quando ele para de chegar, é quase sempre um destes casos.
1. Sua URL está recusando
Só consideramos a entrega bem-sucedida se o seu servidor responder HTTP 2xx (200, 201, 204...) em até 10 segundos. Qualquer outra coisa — 401, 404, 500, tempo esgotado — conta como falha.
Em Desenvolvedor → API Keys → aba Webhooks, clique em Testar no seu webhook: o painel mostra o código que o seu servidor devolveu e o que ele costuma significar.
2. Seu endpoint desligou sozinho
Se a sua URL recusa as entregas repetidamente (10 vezes seguidas), suspendemos as tentativas por 30 minutos e avisamos você por e-mail. Depois de 20 recusas seguidas, o webhook é desativado — reative no painel quando corrigir. É proteção: sem isso, um endpoint quebrado geraria milhares de tentativas inúteis e atrasaria a fila de todo mundo.
Assim que a URL voltar a responder, as entregas são retomadas. Recusas como 401 e 404 não são reenviadas (a resposta seria a mesma); erros 5xx e tempo esgotado são tentados de novo até 5 vezes.
3. A validação da assinatura está errada
Todo webhook vai assinado no cabeçalho X-FlowinPay-Signature. Se o seu código valida a assinatura e a compara de forma incorreta, ele vai rejeitar avisos legítimos.
O guia de webhook na documentação mostra exatamente como calcular e comparar. Os erros mais comuns:
- Secret errado. A chave é o secret do webhook (
whsec_...), completo, com o prefixo — não a API Key (fpk_...). Se você clicou em Regenerar, o secret antigo parou de valer.
- JSON re-serializado. A assinatura é calculada sobre o corpo cru da requisição. Se o seu código converte o JSON e transforma em texto de novo, o texto muda e a assinatura não bate.
- Cabeçalho errado. O nome é
X-FlowinPay-Signature.
Para conferir o cálculo: com o secret whsec_exemploFicticio123 e o corpo {"event":"webhook.test","event_id":"3f2b8c1e-0000-4000-8000-000000000000","timestamp":"2026-10-16T00:24:12+00:00"}, a assinatura tem que dar a05a474d5ebb41024d09060e29f531c7ae589fdd386dea27731abb1d06797a99.
Você não perde pagamento por causa disso
Mesmo que o webhook nunca chegue, o sistema confere sozinho, a cada 5 minutos, quais cobranças foram pagas na instituição financeira. O saldo entra do mesmo jeito. O webhook acelera o seu processo, mas não é o que garante o dinheiro.
Testando
Você pode disparar um evento de teste pelo painel, em Desenvolvedor → API Keys → aba Webhooks → Testar. Ele chega com a mesma assinatura de uma entrega real, então serve para validar seu código antes de ir para produção.
O evento de teste é o webhook.test e não traz dados de cobrança. Seu código precisa responder 2xx para ele — se rejeitar eventos que não conhece, o teste vai falhar mesmo com a assinatura certa.
Central de ajuda · FlowinPay