Developer Documentation

x-veltia-signature: t=1717253119,v1=5e884898da28047151...

{
  "event": "trust_event.finalized",
  "created_at": "2026-02-15T03:00:00Z",
  "data": {
    "id": "evt_8k93...x2",
    "doc_hash": "e3b0c4...41",
    "trust_level": 30,
    "is_live": false,
    "trust_receipt": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, webhookSecret) {
  // 1. Parse header (t=timestamp, v1=signature)
  const parts = signatureHeader.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).split('=')[1];
  const signature = parts.find(p => p.startsWith('v1=')).split('=')[1];

  // 2. Prevent Replay Attacks: Reject if timestamp is older than 5 minutes (300s)
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
  if (Math.abs(age) > 300) {
    throw new Error('Webhook timestamp expired. Replay attack blocked.');
  }

  // 3. Compute expected signature using raw request body
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // 4. Secure constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}