Webhooks: recebendo eventos

{
  "id": "whd_bnl41fsjd33ndrgvx08s59a4i",
  "type": "transaction.paid",
  "data": {
    "id": "txn_bnht3sucidgqm04w8clzfmh7h",
    "status": "paid",
    "amount": 15000,
    "paymentMethod": "credit_card"
  },
  "occurredAt": "2026-06-24T18:32:05.184Z",
  "companyId": "comp_a67vga3rx8fbg4eg4gay8m3a5"
}

X-Webhook-Signature = hex( HMAC-SHA256(secret, rawBody) )

import { createHmac, timingSafeEqual } from 'node:crypto';

/**
 * Valida a assinatura de um webhook da Z2Pay.
 *
 * @param {string} rawBody  Corpo bruto da requisição (string), NÃO re-serializado.
 * @param {string} signature Valor do cabeçalho 'x-webhook-signature'.
 * @param {string} secret   O secret cadastrado no webhook.
 * @returns {boolean}
 */
function verifyWebhookSignature(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');

  // Comprimentos diferentes -> assinatura inválida (timingSafeEqual exige tamanhos iguais)
  if (expected.length !== signature.length) return false;

  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

import express from 'express';

const app = express();

// Captura o raw body como string ANTES de qualquer parse de JSON.
app.use('/webhooks/z2pay', express.raw({ type: 'application/json' }));

app.post('/webhooks/z2pay', (req, res) => {
  const rawBody = req.body.toString('utf8');
  const signature = req.header('x-webhook-signature');

  // Sem o cabeçalho de assinatura, rejeite antes de qualquer processamento.
  if (!signature) {
    return res.status(401).send('missing signature');
  }

  const ok = verifyWebhookSignature(rawBody, signature, process.env.Z2PAY_WEBHOOK_SECRET);
  if (!ok) {
    return res.status(401).send('invalid signature');
  }

  const event = JSON.parse(rawBody);

  // TODO: enfileirar/processar de forma assíncrona; responda rápido.
  console.log('Evento recebido:', event.type, event.id);

  return res.status(200).send('ok');
});