POST fingindo ser a NyxPag. A assinatura é o que impede isso: sem validar, um atacante marca um pedido como pago sem ter pago.
O que a NyxPag envia
Toda entrega é umPOST com Content-Type: application/json e estes cabeçalhos:
Como a assinatura é calculada
A NyxPag calcula um HMAC-SHA256 sobre o texto<t>.<corpo bruto> e envia o resultado em hexadecimal no campo v1.
1
Separe t e v1
Divida o cabeçalho por vírgula e depois cada parte por
=. Se faltar t ou v1, rejeite.2
Cheque o timestamp
Rejeite se
t estiver a mais de 5 minutos do seu relógio. Isso barra reenvio de uma entrega antiga capturada por terceiros.3
Monte o conteúdo assinado
Concatene
t, um ponto e o corpo bruto, byte a byte, exatamente como chegou.4
Calcule o HMAC
HMAC-SHA256 com o segredo do webhook como chave, saída em hexadecimal.
5
Compare em tempo constante
Use a função segura da sua linguagem. Comparar com
== vaza informação pelo tempo de resposta.Qual é a chave
A chave é o segredo de assinatura do webhook. Ele aparece uma única vez, na criação do endpoint em Dashboard → Webhooks, e pode ser trocado com Rotacionar segredo. Guarde como qualquer credencial.Chaves antigas que nunca tiveram um endpoint de webhook configurado assinam com o SHA-256 da API Key em hexadecimal, tratado como texto. Se a sua integração usa só
webhookUrl por requisição e você não tem um segredo no painel, é esse o caso. Para sair dele, crie um endpoint em Dashboard → Webhooks.Vetor de teste
Use estes valores para conferir sua implementação antes de ligar em produção. O resultado foi calculado de forma independente com OpenSSL e Node.js.cURL
Implementação
Erros comuns
A assinatura nunca bate
A assinatura nunca bate
Quase sempre é o corpo: o framework fez parse e você reserializou, ou um middleware alterou o texto. Valide com o vetor de teste acima usando o corpo bruto. Confirme também que você está usando o segredo do webhook e não a API Key.
Funciona local e falha em produção
Funciona local e falha em produção
Proxies e gateways (Nginx, Cloudflare, API Gateway) às vezes reescrevem o corpo ou comprimem. Garanta que a rota do webhook receba o corpo sem transformação.
Rejeita todo evento por timestamp
Rejeita todo evento por timestamp
O relógio do seu servidor está fora de hora. Sincronize com NTP. A tolerância de 5 minutos é sugestão sua, não da NyxPag: ajuste se precisar.
Troquei o segredo e os eventos pararam de validar
Troquei o segredo e os eventos pararam de validar
Depois de Rotacionar segredo, o valor antigo deixa de assinar. Atualize o segredo no seu servidor antes ou logo depois de rotacionar.
Eventos de transação
O formato de
transaction.approved, failed e cancelled.Eventos de MED
O formato de
med.created e med.updated.
