Segurança e Validação
Como validar as requisições com assinatura HMAC.
Toda chamada vai assinada. Verificar essa assinatura garante que a requisição veio da Leaper e que ninguém alterou o conteúdo no caminho — sem isso, qualquer pessoa que descubra a URL do seu endpoint pode enviar dados falsos.
Como validar
- 1Pegue o secretNa tela de Webhooks, clique em 'Ver secret' e copie o valor. Guarde em variável de ambiente no seu servidor, nunca no código.
- 2Assine o corpo brutoCalcule o HMAC-SHA256 sobre os bytes exatos que chegaram, antes de qualquer conversão para objeto. Se fizer JSON.parse e depois JSON.stringify de novo, a ordem das chaves pode mudar e a assinatura nunca vai bater.
- 3Compare com tempo constanteO resultado, prefixado por 'sha256=', deve bater com o header X-Webhook-Signature. Use comparação de tempo constante (hmac.compare_digest em Python, crypto.timingSafeEqual em Node) — nunca ==.
- 4Rejeite se não baterSe a assinatura não bater, responda 401 Unauthorized e nunca processe a requisição.
Exemplo em Node.js
const crypto = require('crypto'); const recebida = req.header('X-Webhook-Signature') || ''; const esperada = 'sha256=' + crypto.createHmac('sha256', process.env.LEAPER_WEBHOOK_SECRET).update(req.body).digest('hex'); const a = Buffer.from(recebida), b = Buffer.from(esperada); if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401); Exemplos completos em Node, PHP e Python estão em verificar a assinatura.
Dicas
- Trate repetições: uma entrega pode chegar mais de uma vez. O campo event_id identifica a entrega e se repete nas retentativas — guarde os que já processou e descarte o que voltar.
- Use o code, não o name: nomes de etapa podem ser renomeados no painel; os códigos são estáveis.
- Aceite campos novos: podemos acrescentar campos ao payload sem aviso. Ignore o que não conhece em vez de falhar.
- Se suspeitar que o secret foi comprometido, exclua o webhook e crie um novo — um novo secret será gerado.