Skip to main content

Validacao de assinatura

A Rewrite assina toda entrega de webhook antes dela chegar ao seu endpoint. Voce deve validar essa assinatura antes de fazer parse do JSON ou executar qualquer logica de negocio.

Headers assinados

Toda entrega assinada inclui estes headers:
  • svix-id Id unico da tentativa de entrega do webhook.
  • svix-timestamp Timestamp usado quando a request foi assinada.
  • svix-signature Header de assinatura usado na verificacao.

O que a Rewrite assina

A assinatura e calculada a partir desta string exata:
Detalhes importantes:
  • payload precisa ser o raw body exato da request.
  • Nao faca JSON.parse(...) antes da verificacao.
  • Nao serialize o payload de novo antes da verificacao.
  • Nao remova espacos nem altere a codificacao.
Se o body mudar em um unico byte, a assinatura calculada nao vai bater.

Qual segredo usar

Use o segredo de assinatura do webhook retornado por:
  • POST /webhooks
  • GET /webhooks/{id}
Nao use sua API key da Rewrite para verificar webhooks. O formato publico do segredo normalmente comeca com whsec_....

Fluxo de verificacao

  1. Leia o raw body da request como string.
  2. Leia svix-id, svix-timestamp e svix-signature.
  3. Decodifique o segredo do webhook em bytes de chave.
  4. Calcule um HMAC-SHA256 sobre ${svix-id}.${svix-timestamp}.${payload}.
  5. Codifique o digest em base64.
  6. Compare a assinatura recebida com a calculada usando comparacao em tempo constante.
  7. So depois disso faca parse do JSON e processe o evento.

Exemplos de funcao de verificacao

As funcoes abaixo sao independentes de framework. Passe a string exata do raw body e os valores originais dos headers svix-* exatamente como chegaram. A aba Node segue o mesmo padrao de verificacao usado pela biblioteca Node da Rewrite.

Endurecimento recomendado

A verificacao da assinatura prova integridade, mas voce tambem pode aplicar sua propria janela aceitavel de tempo com svix-timestamp quando o seu modelo de ameaca exigir controles mais rigidos.
Persista svix-id ou o id do evento de webhook e ignore duplicados com seguranca. A entrega e at-least-once e retries podem acontecer.
Retorne 2xx rapidamente depois da verificacao e mova o trabalho lento para jobs, filas ou workers.
Logue contexto suficiente para depurar requests invalidas, mas evite registrar segredos ou payloads sensiveis em locais inseguros.

Erros comuns

  • Usar express.json() ou outro body parser antes da verificacao.
  • Verificar contra a API key em vez do segredo do webhook.
  • Serializar novamente um JSON ja parseado antes de calcular a assinatura.
  • Remover ou renomear os headers svix-* em proxies ou middleware.
  • Usar comparacao normal de string em vez de comparacao em tempo constante.

Paginas relacionadas