Validação de Assinatura HMAC

Todas as notificações de webhook disparadas pela KavroPay incluem uma assinatura criptográfica HMAC-SHA256 para garantir que a requisição partiu legitimamente dos servidores da KavroPay e que o payload não foi interceptado ou adulterado.

Estrutura dos Cabeçalhos

A assinatura é transmitida no cabeçalho X-KavroPay-Signature (e paralelamente em X-Kavro-Signature e x-kavropay-signature para retrocompatibilidade) no seguinte padrão:

X-KavroPay-Signature: t=1729034291,v1=a3b2c1d0e9f8...
X-Kavro-Timestamp: 1729034291

Onde:

t: Timestamp Unix em segundos no momento exato do disparo.
v1: Hash hexadecimal HMAC-SHA256 gerado a partir do payload bruto.

Segredo Criptográfico (whsec_...): Todos os segredos de webhook utilizam 32 bytes de entropia aleatória com prefixo whsec_ (ex: whsec_3f8a...). Na criação de cobranças com notification_url, o segredo exclusivo daquela transação é retornado no campo notification_secret. Para webhooks cadastrados, consulte via GET /v1/webhooks/:id/secret.

Suporte a Rotação de Chaves (Dual-Signature): Durante a rotação de segredo (POST /v1/webhooks/:id/rotate-secret), a KavroPay suporta uma janela de transição de 24 horas onde envia múltiplos hashes v1 no cabeçalho: t=...,v1={hash_novo},v1={hash_antigo}. Seu código deve validar se qualquer uma das assinaturas v1 corresponde à sua chave.

Como a Assinatura é Calculada

Extraia o timestamp t e o hash v1 do cabeçalho X-Kavro-Signature (ou utilize o cabeçalho X-Kavro-Timestamp).
Concatene o timestamp com o corpo bruto da requisição (raw body, em formato string/bytes, sem alteração de formatação), separado por um ponto: $\text{payloadToSign} = \text{timestamp} + "." + \text{rawBody}$
Calcule o hash HMAC com algoritmo SHA-256 utilizando o segredo do webhook (signingSecret) cadastrado no painel da KavroPay.
Compare o hash calculado com o valor v1 utilizando comparação segura em tempo constante (timing-safe comparison).
Valide se a diferença entre o timestamp do webhook e o relógio atual do seu servidor não ultrapassa 300 segundos (5 minutos) para evitar ataques de repetição (replay attacks).

Exemplos Práticos de Implementação

Node.js (Express / Fastify)
Python (FastAPI / Flask)
PHP

const crypto = require('crypto');

/**
 * Valida a assinatura HMAC de um webhook KavroPay
 * @param {string} rawBody - Corpo bruto da requisição HTTP (Buffer ou string crua)
 * @param {string} signatureHeader - Valor do header 'x-kavro-signature' (ex: "t=1729034291,v1=...")
 * @param {string} webhookSecret - Segredo do webhook configurado no painel KavroPay
 * @param {number} toleranceSeconds - Tolerância máxima de desvio do relógio (padrão: 300s)
 * @returns {boolean}
 */
function verifyKavroSignature(rawBody, signatureHeader, webhookSecret, toleranceSeconds = 300) {
  if (!signatureHeader || !webhookSecret) return false;

  // 1. Extrair timestamp e hash v1
  const parts = signatureHeader.split(',');
  const timestampPart = parts.find(p => p.startsWith('t='));
  const signaturePart = parts.find(p => p.startsWith('v1='));

  if (!timestampPart || !signaturePart) return false;

  const timestamp = parseInt(timestampPart.substring(2), 10);
  const signature = signaturePart.substring(3);

  // 2. Proteção contra Replay Attacks (tolerância de 5 minutos)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) {
    return false;
  }

  // 3. Montar a string assinada: "{timestamp}.{rawBody}"
  const payloadToSign = `${timestamp}.${rawBody}`;

  // 4. Calcular o HMAC-SHA256
  const expectedHmac = crypto
    .createHmac('sha256', webhookSecret)
    .update(payloadToSign)
    .digest('hex');

  // 5. Comparação em tempo constante contra timing attacks
  if (signature.length !== expectedHmac.length) return false;

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedHmac, 'hex')
  );
}

// Exemplo de uso no Express com express.raw():
// app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
//   const sig = req.headers['x-kavro-signature'] || req.headers['x-kavropay-signature'];
//   const rawBody = req.body.toString('utf8');
//   const isValid = verifyKavroSignature(rawBody, sig, process.env.KAVRO_WEBHOOK_SECRET);
//   if (!isValid) return res.status(401).send('Assinatura inválida');
//   const event = JSON.parse(rawBody);
//   // Processar evento...
//   res.status(200).send({ received: true });
// });

import hmac
import hashlib
import time

def verify_kavro_signature(raw_body: bytes, signature_header: str, webhook_secret: str, tolerance_seconds: int = 300) -> bool:
    if not signature_header or not webhook_secret:
        return False

    # 1. Extrair timestamp e v1
    pairs = dict(item.split("=", 1) for item in signature_header.split(",") if "=" in item)
    timestamp_str = pairs.get("t")
    received_sig = pairs.get("v1")

    if not timestamp_str or not received_sig:
        return False

    # 2. Tolerância contra replay attacks
    timestamp = int(timestamp_str)
    if abs(int(time.time()) - timestamp) > tolerance_seconds:
        return False

    # 3. Montar string assinada
    payload_to_sign = f"{timestamp}.".encode("utf-8") + raw_body

    # 4. Calcular HMAC-SHA256
    expected_hmac = hmac.new(
        webhook_secret.encode("utf-8"),
        payload_to_sign,
        hashlib.sha256
    ).hexdigest()

    # 5. Comparação segura
    return hmac.compare_digest(received_sig, expected_hmac)

<?php
/**
 * Valida a assinatura de webhook da KavroPay
 */
function verifyKavroSignature(string $rawBody, ?string $signatureHeader, string $webhookSecret, int $tolerance = 300): bool {
    if (!$signatureHeader || !$webhookSecret) {
        return false;
    }

    // 1. Extrair componentes t e v1
    $items = explode(',', $signatureHeader);
    $timestamp = null;
    $receivedSignature = null;

    foreach ($items as $item) {
        if (str_starts_with($item, 't=')) {
            $timestamp = (int) substr($item, 2);
        } elseif (str_starts_with($item, 'v1=')) {
            $receivedSignature = substr($item, 3);
        }
    }

    if (!$timestamp || !$receivedSignature) {
        return false;
    }

    // 2. Prevenir replay attacks
    if (abs(time() - $timestamp) > $tolerance) {
        return false;
    }

    // 3. Montar payload assinado
    $payloadToSign = $timestamp . '.' . $rawBody;

    // 4. Calcular HMAC-SHA256
    $expectedHmac = hash_hmac('sha256', $payloadToSign, $webhookSecret);

    // 5. Comparação em tempo constante
    return hash_equals($receivedSignature, $expectedHmac);
}

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Validação de Assinatura HMAC

Estrutura dos Cabeçalhos

Como a Assinatura é Calculada

Exemplos Práticos de Implementação