Signature Verification

​

What signature verification proves

• Authenticity. Only a party with the subscription’s secret could have generated the signature. Since the secret is known only to your integration and Virtuous, a valid signature confirms the request originated from Virtuous.
• Integrity. The signature is computed over the request body. Any modification of the body in transit invalidates the signature.

• Freshness. A captured-and-replayed request has a valid signature. Use a delivery timestamp and a short window (e.g., reject events older than five minutes) to defend against replay attacks. Combined with idempotency on event IDs, this is sufficient for most production receivers.
• Authorization. The signature only proves the request is genuine. Whether the event represents something your integration should act on is a separate concern — handled by your business logic, not your verifier.

​

The verification pattern

1. Virtuous computes signature = HMAC-SHA256(secret, request_body) at delivery time.
2. The signature is delivered in a request header (typically named something like X-Virtuous-Signature).
3. Your receiver reads the raw request body (before JSON parsing), computes the same HMAC using your stored secret, and compares the result to the signature header in constant time.
4. If the signatures match, the request is accepted. If not, the request is rejected with 401 Unauthorized.

• Use the raw body. Signature verification operates on the exact bytes Virtuous sent. JSON-parsing-then-re-serializing changes whitespace, key ordering, and number formatting — all of which invalidate the signature.
• Compare in constant time. A naive string comparison reveals timing information that lets an attacker iterate toward a valid signature. Use a constant-time comparison primitive from your language’s crypto library.

​

Verification code

import crypto from 'crypto';

// The exact header name Virtuous uses is not yet confirmed.
// Update once published.
const SIGNATURE_HEADER = 'x-virtuous-signature';

export function verifyVirtuousSignature(rawBody, headers, secret) {
  const receivedSignature = headers[SIGNATURE_HEADER];
  if (!receivedSignature) {
    return false;
  }

  // Compute the expected signature over the raw body.
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  // Constant-time comparison to defend against timing attacks.
  const expectedBuffer = Buffer.from(expectedSignature, 'hex');
  const receivedBuffer = Buffer.from(receivedSignature, 'hex');

  if (expectedBuffer.length !== receivedBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(expectedBuffer, receivedBuffer);
}

• express.raw({ type: 'application/json' }) captures the request body as a Buffer instead of parsing it as JSON. Standard express.json() middleware parses and discards the raw bytes, breaking signature verification. Use raw for the webhook route only.
• crypto.timingSafeEqual compares two equal-length Buffers in constant time. Standard === comparison short-circuits on the first differing byte, leaking timing information.

​

Handling signature failures

if (!valid) {
  console.warn('Webhook signature verification failed', {
    ip: req.ip,
    userAgent: req.headers['user-agent'],
    timestamp: new Date().toISOString(),
    // Do NOT log the raw body or the secret — both could leak sensitive data.
  });
  return res.status(401).send('Invalid signature');
}

• Secret rotation in flight. During a secret rotation, deliveries in transit may still be signed with the old secret. Accept both old and new secrets during the rotation window. See Webhooks Overview.
• Body modification by an intermediate proxy. Some load balancers and WAFs modify request bodies (re-encoding, header normalization). If you see consistent signature failures from a specific source, suspect a proxy. Configure the proxy to pass the body through unmodified.

​

Replay protection

​

1. Timestamp window

const MAX_AGE_SECONDS = 5 * 60; // 5 minutes

function isWithinFreshnessWindow(event) {
  if (!event.timestamp) return false;
  const eventTime = new Date(event.timestamp).getTime();
  const ageSeconds = (Date.now() - eventTime) / 1000;
  return ageSeconds < MAX_AGE_SECONDS;
}

​

2. Event ID idempotency

async function processWithIdempotency(event) {
  const alreadyProcessed = await idempotencyStore.has(event.eventId);
  if (alreadyProcessed) {
    return; // Already handled — drop the duplicate.
  }
  await idempotencyStore.set(event.eventId, { processedAt: new Date() });
  await processVirtuousEvent(event);
}

​

Testing your verifier

​

Self-signed test fixtures

import crypto from 'crypto';

function generateTestSignature(body, secret) {
  return crypto.createHmac('sha256', secret).update(body).digest('hex');
}

// In a test
const testBody = Buffer.from(JSON.stringify({ eventType: 'contact.created' }));
const testSecret = 'test-secret';
const testHeaders = {
  'x-virtuous-signature': generateTestSignature(testBody, testSecret),
};

expect(verifyVirtuousSignature(testBody, testHeaders, testSecret)).toBe(true);
expect(verifyVirtuousSignature(testBody, testHeaders, 'wrong-secret')).toBe(false);

​

Live replay against the Seeded Sandbox

​

Security checklist

• Signature verification runs on every request before any processing.
• The raw request body is used for signature computation (not the parsed JSON).
• Signature comparison uses a constant-time primitive (crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python).
• The shared secret is loaded from a secrets manager — never hardcoded.
• Failed signature attempts are logged with enough context to investigate, but the raw body, the secret, and the signature value are not logged.
• The endpoint is HTTPS-only with a valid public certificate.
• Replay protection is in place: timestamp window, event ID idempotency, or both.
• Secret rotation is supported: your verifier can accept multiple valid secrets simultaneously during a rotation window.

​

Where to go next