Skip to main content
Qualquer pessoa que descubra a URL do seu webhook pode enviar um POST fingindo ser a NyxPag. A assinatura é o que impede isso: sem validar, um atacante marca um pedido como pago sem ter pago.
Valide a assinatura antes de qualquer efeito colateral: liberar produto, creditar saldo, enviar e-mail. Se a validação falhar, descarte o evento.

O que a NyxPag envia

Toda entrega é um POST 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.
O corpo precisa ser o bruto. Se o seu framework faz parse do JSON e você reserializa, espaços e ordem de chaves mudam e a assinatura nunca bate. No Express use express.raw, no Flask use request.get_data(), no PHP use file_get_contents('php://input').

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

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.
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.
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.
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.