Receiving Webhooks

const express = require('express');
const crypto = require('crypto');

const app = express();

function verifySignature(payload, signatureHeader, signingSecret) {
  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 = timestampPart.split('=')[1];
  const receivedSignature = signaturePart.split('=')[1];

  // timingSafeEqual throws if the two buffers differ in length, so reject
  // anything that is not a full SHA-256 hex digest before comparing.
  if (!/^[0-9a-f]{64}$/i.test(receivedSignature)) {
    return false;
  }

  const message = `${timestamp}.${payload}`;

  const calculatedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(receivedSignature, 'hex'),
    Buffer.from(calculatedSignature, 'hex')
  );
}

// express.raw() keeps req.body as an untouched Buffer of raw bytes,
// which is required for signature verification to succeed.
app.post('/webhooks/soap', express.raw({ type: 'application/json' }), (req, res) => {
  const signatureHeader = req.headers['soap-webhook-signature'];
  const payload = req.body.toString('utf8');

  if (!signatureHeader || !verifySignature(payload, signatureHeader, process.env.SOAP_WEBHOOK_SECRET)) {
    return res.status(422).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  switch (event.type) {
    case 'checkout.hold': {
      // Respond 2xx if the customer has sufficient funds, non-2xx otherwise.
      // This must complete quickly — checkout.hold is synchronous and not retried.
      const hasSufficientFunds = true; // your balance check here
      return res.sendStatus(hasSufficientFunds ? 200 : 402);
    }

    case 'checkout.succeeded':
      // Enqueue async processing, then respond quickly.
      enqueueLedgerUpdate(event);
      return res.sendStatus(200);

    default:
      // Acknowledge events you don't act on yet so Soap doesn't retry them.
      return res.sendStatus(200);
  }
});

function enqueueLedgerUpdate(event) {
  // Use event.event_id as your idempotency key before applying the update.
}