Segurança
🔐 Validação de Assinatura de Webhooks
Para garantir a autenticidade e a integridade das notificações enviadas pelo nosso sistema, todos os webhooks são assinados utilizando um segredo compartilhado (webhook secret), que realiza a assinatura do payload via HMAC SHA-256.
📌 Como funciona
Cada requisição enviada contém:
O payload (corpo da requisição)
Um header HTTP:
X-Signature: {assinatura}Essa assinatura é gerada aplicando um HMAC SHA-256 sobre o payload bruto utilizando o token de segurança configurado:

🎯 Objetivo da validação
O sistema receptor deve validar a assinatura para garantir:
✔️ Que o payload não foi alterado (integridade)
✔️ Que a requisição foi enviada por um remetente confiável (autenticidade)
✔️ Que a comunicação é segura contra ataques de replay ou spoofing
⚙️ Passo a passo para validação
Ao receber o webhook, seu sistema deve:
Ler o payload bruto da requisição
Importante: não utilize payload já parseado (ex: JSON decodificado)
Obter o header
X-SignatureGerar uma nova assinatura localmente
Utilizando:
O payload bruto
O secret compartilhado
Comparar as assinaturas
Utilize comparação segura (timing-safe comparison)
Rejeitar a requisição caso a assinatura seja inválida
Retorne HTTP
403 Forbidden
💻 Exemplo em PHP (Laravel)
💻 Exemplo em NodeJS
⚠️ Boas práticas (importante)
1. Use sempre o payload bruto
Qualquer transformação (ex: json_decode → json_encode) pode invalidar a assinatura.
2. Nunca use comparação simples (===)
Utilize sempre:
3. Proteja seu webhook secret
Nunca exponha no frontend
Armazene em variáveis de ambiente seguras
4. Valide antes de processar
A validação da assinatura deve ser o primeiro passo antes de qualquer lógica de negócio
Atualizado