ZypfyDocs Acessar painel
Guia de integração

Verificando a assinatura dos webhooks

Valide a autenticidade dos webhooks da Zypfy com HMAC-SHA256 (X-Webhook-Signature + X-Webhook-Timestamp).

Todo webhook que a Zypfy envia ao seu sistema é assinado. Use a assinatura para garantir que a notificação veio mesmo da Zypfy e não foi adulterada.

Headers enviados

HeaderDescrição
X-Webhook-SignatureHMAC-SHA256, em hex, do corpo da requisição.
X-Webhook-TimestampUnix time (em segundos) de quando o webhook foi assinado.

Como a assinatura é calculada

código
assinatura = HMAC_SHA256(secret, `${X-Webhook-Timestamp}.${corpo_bruto}`)

Passos recomendados

  1. Leia o corpo bruto da requisição (sem fazer parse/round-trip do JSON).
  2. Leia os headers X-Webhook-Signature e X-Webhook-Timestamp.
  3. Rejeite se o timestamp estiver a mais de 5 minutos do horário atual (proteção contra replay).
  4. Recompute o HMAC e compare com X-Webhook-Signature usando comparação timing-safe.

Exemplo — Node.js (Express)

js
const crypto = require('crypto');

// Capture o corpo BRUTO (ex.: express.raw) para não re-serializar o JSON.
app.post('/webhooks/zypfy', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.ZYPFY_WEBHOOK_SECRET;
  const signature = req.header('X-Webhook-Signature') || '';
  const timestamp = req.header('X-Webhook-Timestamp') || '';

  // Anti-replay: 5 minutos.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(401).json({ error: 'timestamp expirado' });
  }

  const rawBody = req.body.toString('utf8');
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(signature, 'hex');
  const b = Buffer.from(expected, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).json({ error: 'assinatura invalida' });
  }

  const evento = JSON.parse(rawBody);
  // ... processa o evento ...
  return res.json({ ok: true });
});

Exemplo — PHP

php
<?php
$secret    = getenv('ZYPFY_WEBHOOK_SECRET');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$rawBody   = file_get_contents('php://input');

// Anti-replay: 5 minutos.
if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit('timestamp expirado');
}

$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('assinatura invalida');
}

$evento = json_decode($rawBody, true);
// ... processa o evento ...
http_response_code(200);
echo json_encode(['ok' => true]);

Notas