Introdução
Webhooks permitem que você receba notificações em tempo real quando eventos importantes ocorrem, como pagamentos aprovados, saques concluídos e disputas MED. Em vez de fazer polling constante para verificar o status, o sistema envia automaticamente uma notificação para sua URL configurada.Configurando Webhooks
URL do webhook: Sua URL de webhook deve estar acessível publicamente via HTTPS e responder com status 200 para requisições POST.
Estrutura do Webhook
Todos os webhooks são enviados com a seguinte estrutura:Headers Enviados
Cada requisição de webhook inclui os seguintes headers:Eventos de Webhook
Eventos de Pagamento
payment.created
payment.created
Enviado quando um novo pagamento PIX é criado (mas ainda não pago).Payload:
payment.approved
payment.approved
Enviado quando um pagamento PIX é confirmado e o valor é creditado.Payload:
payment.expired
payment.expired
Enviado quando um pagamento PIX expira sem ser pago.Payload:
Eventos de Reembolso
refund.created
refund.created
Enviado quando um reembolso é iniciado.Payload:
refund.completed
refund.completed
Enviado quando um reembolso é processado com sucesso.Payload:
refund.failed
refund.failed
Enviado quando um reembolso falha durante o processamento.Payload:
Eventos de Saque
withdrawal.created
withdrawal.created
Enviado quando um saque é criado (iniciado).Payload:
withdrawal.completed
withdrawal.completed
Enviado quando um saque é processado com sucesso.Payload:
withdrawal.failed
withdrawal.failed
Enviado quando um saque falha durante o processamento.Payload:
Eventos de MED (Mecanismo Especial de Devolução)
med.created
med.created
Enviado quando uma nova infração MED é criada no sistema.Payload:
med.won
med.won
Enviado quando você vence uma disputa MED e o valor é liberado.Payload:
med.lost
med.lost
Enviado quando você perde uma disputa MED e o valor é devolvido ao pagador.Payload:
Implementando o Webhook Endpoint
Seu servidor deve responder às requisições de webhook corretamente:Requisitos do Endpoint
Responda com status 2xx
Responda com status 2xx
Seu endpoint deve retornar um código de status HTTP 2xx (200, 201, 204) para confirmar o recebimento:Qualquer outro status será considerado uma falha e o webhook será reenviado.
Erros 4xx (400-499) não são reenviados, pois indicam problemas no seu lado que não serão resolvidos com retentativas.
Timeout de 10 segundos
Timeout de 10 segundos
Seu servidor tem 10 segundos para responder. Se exceder esse tempo, consideramos a tentativa como falha.Dica: Processe operações demoradas de forma assíncrona:
Idempotência
Idempotência
O mesmo webhook pode ser enviado mais de uma vez. Implemente idempotência para evitar processamento duplicado:
Segurança
Verificação de Assinatura
Cada webhook é assinado usando HMAC-SHA256 com sua API Key como secret. Sempre verifique a assinatura para garantir que o webhook é autêntico.Validação Adicional
Além da assinatura, você pode validar o timestamp para prevenir ataques de replay:Outras Medidas de Segurança
Use HTTPS
Use HTTPS
Configure seu webhook endpoint apenas com HTTPS para garantir que os dados sejam criptografados em trânsito.
Restrinja IPs (opcional)
Restrinja IPs (opcional)
Se necessário, você pode restringir o acesso ao seu endpoint apenas ao IP da NeverMiss:
169.197.93.2.Retentativas
Se seu endpoint falhar ao receber um webhook (timeout, erro 5xx, etc), o sistema usa backoff exponencial para reenviar:1
Tentativa 1
Imediatamente
2
Tentativa 2
Após 2 segundos (delay base × 2^0)
3
Tentativa 3
Após 4 segundos (delay base × 2^1)
4
Tentativa 4
Após 8 segundos (delay base × 2^2)
5
Tentativa 5
Após 16 segundos (delay base × 2^3) - última tentativa
Após todas as tentativas falharem, o webhook é descartado. Você pode consultar o status manualmente via API.Importante: Erros 4xx (como 400, 401, 404) não são reenviados, pois indicam problemas de configuração que não serão resolvidos automaticamente.
Testando Webhooks
Desenvolvimento Local
Para testar webhooks localmente, use ferramentas como ngrok para expor seu servidor local:Logs e Debugging
Adicione logs detalhados para facilitar o debugging:Lista de Eventos
Callback URL vs Webhook
Entenda a diferença entre estas duas configurações:
Você pode (e deve) configurar ambos para uma experiência completa!