Validação do Header Assinado

Se o seu endpoint de webhook está público na web, bots escaneadores ou atacantes podem tentar forjar pagamentos submetendo requisições falsas.

A forma definitiva de atestar a origem e a integridade (não-alteralção de body) da transação é através de Recálculo de Algoritmos HMAC-SHA256 suportado pelas nossas integrações.

1. Obtendo os dados da Requisição

Quando a nossa plataforma faz um POST de conciliação Webhook na sua URL, são embutidos Header customizados, do qual destacamos o X-Webhook-Signature que possuirá a estrutura sha256=<hmac_criada>

2. Recalculando o Hash no seu Software

Pegue o Raw Body Text (antes do parse JSON) recebido, e faça a conversão contra a webhook_secret que obtivemos no Cadastro de sua URL de Recebimento. Não se esqueça de decodificar como HEX String. Se os Hashes divergirem, emita um erro HTTP 401 ou 403 no framework, fechando a conexão e matando esse worker imediatamente.

Exemplo usando NodeJS/Express:

const crypto = require('crypto');

app.post('/meu-receiver-url', express.raw({type: 'application/json'}), (req, res) => {
    
    // O Segredo Cadastrado e Resgatado via POST /config/webhooks/
    const WEBHOOK_SECRET = process.env.WH_SECRET_DA_URL; 
    
    // Header da Requisiçao Realizada por nós
    const signatureRecebida = req.headers['x-webhook-signature'];
    
    // Hash local refazendo os passos matematicos
    const hashGeradoHmac = crypto
          .createHmac('sha256', WEBHOOK_SECRET)
          .update(req.body)
          .digest('hex');
          
    const stringEsperada = `sha256=${hashGeradoHmac}`;
    
    if (signatureRecebida !== stringEsperada) {
       return res.status(401).send("Ataque contido, payload modificado ou originário não esperado!");
    }
    
    // Se a execução cair aqui, a mensagem pertence de fato a nossa plataforma
    const payload = JSON.parse(req.body);
    return res.status(200).send("OK!");
});