Por que verificar a assinatura
A verificação garante que o payload recebido foi gerado pela ClearPago e não foi adulterado em trânsito. Nunca processe um webhook sem verificar a assinatura — isso é um requisito de segurança, não uma recomendação.Como funciona
A ClearPago assina o corpo bruto (raw body) da requisição com ECDSA P-256 + SHA-256 e inclui a assinatura em Base64 no headerDigital-Signature.
GET /public-key.
Passo 1 — Obter e armazenar a chave pública
Boas práticas de cache
- Faça cache da chave com um TTL razoável (ex.: 1 hora ou 24 horas).
- Prepare rotação: implemente lógica para buscar novamente a chave se a verificação falhar com a versão em cache.
- Nunca hardcode a chave no código — busque programaticamente.
Passo 2 — Preservar o corpo bruto
A assinatura é calculada sobre o corpo bruto da requisição, antes do parse JSON. Configure seu framework para disponibilizar o buffer original. Express (Node.js):Passo 3 — Verificar a assinatura
Node.js (crypto nativo)
Python (cryptography)
Go
TODO: confirmar o formato de encoding da assinatura (DER ASN.1 vs. IEEE P1363) com a implementação. Os exemplos acima usam formatos diferentes — alinhe com o header real enviado pela plataforma.
Checklist de verificação
Corpo bruto preservado antes do parse JSON.
Chave pública obtida de
GET /public-key (não hardcoded).Cache da chave com TTL e rotação automática em caso de falha.
Verificação ocorre antes de qualquer lógica de negócio.
Retorno
401 quando a assinatura for inválida.Retorno
2xx rápido quando a assinatura for válida.Lógica de negócio executada de forma assíncrona.

