Webhooks

Webhook security and testing endpoints.

HiringCenter signs outbound webhook requests with the per-webhook endpoint secret and includes:

X-HiringCenter-Signature: t=<unix_timestamp>,v1=<hex_hmac>

During secret-rotation grace windows, the header can contain multiple v1 values:

X-HiringCenter-Signature: t=<unix_timestamp>,v1=<current_hex>,v1=<previous_hex>

Each v1 is computed as:

HMAC_SHA256(endpointSecret, t + "." + rawBody)

Verification rules:

1. Use the exact raw request body bytes/string (no JSON parse + re-serialize).
2. Parse t and all v1 values from the header.
3. Enforce timestamp tolerance (recommended: 300 seconds) for replay protection.
4. Compute expected signature once: expected = HMAC_SHA256(endpointSecret, t + "." + rawBody).
5. Compare in constant time.
6. Accept if any provided v1 matches.
7. Parse JSON only after signature verification succeeds.

Node.js helper:

Code
 
const crypto = require('crypto');

function parseSignatureHeader(signatureHeader) {
  if (!signatureHeader || typeof signatureHeader !== 'string') return null;
  const parts = signatureHeader.split(',').map((part) => part.trim()).filter(Boolean);

  let timestamp = null;
  const signatures = [];

  for (const part of parts) {
    const [k, v] = part.split('=');
    if (!k || !v) continue;
    if (k === 't') {
      const parsed = Number.parseInt(v, 10);
      if (Number.isFinite(parsed)) timestamp = parsed;
    } else if (k === 'v1' && /^[0-9a-fA-F]+$/.test(v)) {
      signatures.push(v.toLowerCase());
    }
  }

  if (!timestamp || signatures.length === 0) return null;
  return { timestamp, signatures };
}

function verifyHiringCenterSignature({ rawBody, signatureHeader, endpointSecret, toleranceSeconds = 300 }) {
  const parsed = parseSignatureHeader(signatureHeader);
  if (!parsed) return false;

  const { timestamp, signatures } = parsed;
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

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

  for (const candidate of signatures) {
    try {
      if (crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(candidate, 'hex'))) {
        return true;
      }
    } catch (_) {}
  }

  return false;
}