Webhooks

Webhook polling, outbound delivery to your HTTPS endpoints, and signature verification.

For the full outbound delivery contract (HTTP request shape, supported event types such as prospect.created, payload envelope, suppression via muteWebhook, and step-by-step signature verification), see x-outboundWebhookDelivery at the end of this document.

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;
}