Skip to main content

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

Configuração de webhook: A configuração de webhooks deve ser feita através do painel de administração ou entrando em contato com o suporte. Não há endpoint público para configurar webhooks via API.
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

Enviado quando um novo pagamento PIX é criado (mas ainda não pago).Payload:
Enviado quando um pagamento PIX é confirmado e o valor é creditado.Payload:
Enviado quando um pagamento PIX expira sem ser pago.Payload:

Eventos de Reembolso

Enviado quando um reembolso é iniciado.Payload:
Enviado quando um reembolso é processado com sucesso.Payload:
Enviado quando um reembolso falha durante o processamento.Payload:

Eventos de Saque

Enviado quando um saque é criado (iniciado).Payload:
Enviado quando um saque é processado com sucesso.Payload:
Enviado quando um saque falha durante o processamento.Payload:

Eventos de MED (Mecanismo Especial de Devolução)

Enviado quando uma nova infração MED é criada no sistema.Payload:
Enviado quando você vence uma disputa MED e o valor é liberado.Payload:
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

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.
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:
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.
Sempre valide a assinatura!Nunca processe webhooks sem verificar a assinatura. Isso protege seu sistema contra requisições forjadas.

Validação Adicional

Além da assinatura, você pode validar o timestamp para prevenir ataques de replay:

Outras Medidas de Segurança

Configure seu webhook endpoint apenas com HTTPS para garantir que os dados sejam criptografados em trânsito.
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!