Por que verificar
Qualquer pessoa pode enviar uma requisição POST para a sua URL de webhook. A assinatura HMAC-SHA256 garante que a requisição veio do Vistum e que o payload não foi adulterado.
Sempre verifique a assinatura antes de processar um evento. Ignorar esta etapa expõe sua integração a ataques de replay e spoofing.
Como funciona
Cada requisição de webhook inclui o header:
t — Unix timestamp da entrega (em segundos)
v1 — HMAC-SHA256 em hex
String assinada:
O HMAC é calculado com o secret do webhook (gerado na criação) como chave.
Verificação por linguagem
Rotação do secret
Se o seu secret de webhook for comprometido, você pode rotacioná-lo sem interromper as entregas:
- Acesse Configurações → Webhooks → [seu webhook] → Rotacionar Secret
- Copie o novo secret
- Atualize a variável de ambiente na sua aplicação
- Faça um deploy da sua aplicação
O Vistum passa a assinar com o novo secret imediatamente após a rotação.
Proteção contra replay
Implemente sempre a verificação de timestamp para rejeitar requisições antigas:
Isso previne que um atacante reenvie uma requisição capturada anteriormente.