Build with DOTCODE Platform

All webhook payloads are signed with HMAC-SHA256. Verify the signature to ensure authenticity.

Headers sent with each webhook:

• X-Stucode-Event-Id - Unique event identifier
• X-Stucode-Delivery-Id - Delivery attempt ID (for idempotency)
• X-Stucode-Timestamp - ISO timestamp
• X-Stucode-Signature - sha256=HMAC signature

The signature covers the raw request body concatenated with the delivery id and the timestamp, in that order. Verify against the bytes you received rather than a re-serialised object — key order is not guaranteed to survive a parse and re-stringify.

Verification (Node.js):

const crypto = require('crypto');

// rawBody: the exact bytes of the request body, before JSON.parse
function verifyWebhook(rawBody, headers, secret) {
  const signature  = headers['x-stucode-signature'];
  const deliveryId = headers['x-stucode-delivery-id'];
  const timestamp  = headers['x-stucode-timestamp'];

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

  // Constant-time compare: a === b leaks how much of the signature matched.
  const a = Buffer.from(signature || '');
  const b = Buffer.from('sha256=' + expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}