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-idId unico da tentativa de entrega do webhook.svix-timestampTimestamp usado quando a request foi assinada.svix-signatureHeader de assinatura usado na verificacao.
O que a Rewrite assina
A assinatura e calculada a partir desta string exata:payloadprecisa 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.
Qual segredo usar
Use o segredo de assinatura do webhook retornado por:POST /webhooksGET /webhooks/{id}
whsec_....
Fluxo de verificacao
- Leia o raw body da request como string.
- Leia
svix-id,svix-timestampesvix-signature. - Decodifique o segredo do webhook em bytes de chave.
- Calcule um HMAC-SHA256 sobre
${svix-id}.${svix-timestamp}.${payload}. - Codifique o digest em base64.
- Compare a assinatura recebida com a calculada usando comparacao em tempo constante.
- 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 headerssvix-* exatamente como chegaram.
A aba Node segue o mesmo padrao de verificacao usado pela biblioteca Node da Rewrite.
Endurecimento recomendado
Rejeite timestamps antigos quando precisar de mais protecao contra replay
Rejeite timestamps antigos quando precisar de mais protecao contra replay
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.Armazene ids de entrega processados
Armazene ids de entrega processados
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.Mantenha o endpoint focado em verificar e enfileirar
Mantenha o endpoint focado em verificar e enfileirar
Retorne
2xx rapidamente depois da verificacao e mova o trabalho lento para jobs, filas ou workers.Registre falhas de verificacao com cuidado
Registre falhas de verificacao com cuidado
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.