Webhooks: overview

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

X-Webhook-Signature = HMAC-SHA256(secret, JSON.stringify(payload))   // in hexadecimal

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

/**
 * Validates the signature of a Z2Pay webhook.
 *
 * @param {string} rawBody  Raw request body (string), NOT re-serialized.
 * @param {string} signature Value of the 'x-webhook-signature' header.
 * @param {string} secret   The secret registered on the webhook.
 * @returns {boolean}
 */
function verifyWebhookSignature(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');

  // Different lengths -> invalid signature (timingSafeEqual requires equal sizes)
  if (expected.length !== signature.length) return false;

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

import express from 'express';

const app = express();

// Capture the raw body as a string BEFORE any JSON parsing.
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');

  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: enqueue/process asynchronously; respond quickly.
  console.log('Evento recebido:', event.type, event.id);

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