REST API webhook signature verification

Verifying webhook signatures

If you configure webhooks to receive events from Certorix, you should verify signatures to ensure requests are genuinely from Certorix, not forged.

How signatures work

1. When you create a webhook, you provide a secret (any random string).
2. Certorix computes an HMAC‑SHA256 signature of the request body using your secret.
3. The signature is included in the X-Certorix-Signature header.
4. Your server computes the same HMAC and compares.

Verification code example (Node.js)

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler
const isValid = verifySignature(req.body, req.headers['x-certorix-signature'], process.env.WEBHOOK_SECRET);
if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Verification code example (Python)

import hmac
import hashlib

def verify_signature(body, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        json.dumps(body, sort_keys=True).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Important notes

• The signature is computed on the raw request body (as bytes), not on a parsed JSON object. Ensure you use the raw body, not a re‑stringified object.
• The signature header is included for all webhook deliveries (success and retry).
• If you do not provide a secret when creating the webhook, the signature header is omitted.
• Regenerating the webhook secret does not invalidate previous signatures for old deliveries.

Testing webhook signatures

Certorix provides a test endpoint. Send a test webhook from the webhook configuration page and inspect your server logs to verify signature validation works.

Timestamp header

Webhook deliveries also include X-Certorix-Timestamp (Unix timestamp). You can optionally reject webhooks older than 5 minutes to prevent replay attacks.