Skip to main content

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 header Digital-Signature.
A chave pública para verificação está disponível em GET /public-key.

Passo 1 — Obter e armazenar a chave pública

Resposta (PEM):

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):
FastAPI (Python):

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.

Troubleshooting

Referências