Pre-release — content may change.

GuidesWebhooks

Webhook Security

Implementing HMAC-SHA256 signature verification for webhooks

Webhook security is critical to ensure that requests actually come from Wicket and not from malicious actors. Wicket signs every webhook with HMAC-SHA256 to verify authenticity.

How Webhook Signing Works

  1. Wicket generates a signature by creating an HMAC-SHA256 hash of the request body using your endpoint's signature_key

  2. The signature is sent in the X-WicketEvents-Signature header with each webhook request

  3. Your server verifies by generating the same HMAC-SHA256 hash and comparing it

  4. If signatures match, the request is authentic; otherwise, reject it

Signature Headers

Each webhook request includes these headers:

X-WicketEvents-Signature: abc123def456...
X-WicketEvents-Host: your-tenant-api.wicketcloud.com
Content-Type: application/json
  • X-WicketEvents-Signature: HMAC-SHA256 hex digest for verification
  • X-WicketEvents-Host: Originating Wicket host

Implementing Verification

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(signatureKey, rawBody, receivedSignature) {
  // Generate expected signature
  const expectedSignature = crypto
    .createHmac('sha256', signatureKey)
    .update(rawBody)
    .digest('hex');

  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(receivedSignature),
    Buffer.from(expectedSignature)
  );
}

// Express middleware example
app.post('/webhooks/wicket',
  express.raw({ type: 'application/json' }), // Get raw body
  (req, res) => {
    const signature = req.headers['x-wicketevents-signature'];
    const rawBody = req.body.toString('utf8');
    const payload = JSON.parse(rawBody);

    // Skip verification for test payloads
    if (payload.test === true) {
      console.log('Test payload received');
      return res.status(200).send('OK');
    }

    // Verify signature
    const isValid = verifyWebhookSignature(
      process.env.WICKET_WEBHOOK_SIGNATURE_KEY,
      rawBody,
      signature
    );

    if (!isValid) {
      console.error('Invalid webhook signature');
      return res.status(401).send('Invalid signature');
    }

    // Process webhook
    res.status(200).send('OK');
    processWebhook(payload);
  }
);

Important: Use the raw request body for verification, not the parsed JSON. Parsing can change whitespace or key ordering, breaking the signature.

Ruby

require 'openssl'

def verify_webhook_signature(signature_key, raw_body, received_signature)
  # Generate expected signature
  expected_signature = OpenSSL::HMAC.hexdigest(
    OpenSSL::Digest.new('sha256'),
    signature_key,
    raw_body
  )

  # Use timing-safe comparison
  Rack::Utils.secure_compare(expected_signature, received_signature)
end

# Sinatra example
require 'sinatra'
require 'json'

post '/webhooks/wicket' do
  signature = request.env['HTTP_X_WICKETEVENTS_SIGNATURE']
  raw_body = request.body.read
  payload = JSON.parse(raw_body)

  # Skip verification for test payloads
  if payload['test'] == true
    puts 'Test payload received'
    return [200, 'OK']
  end

  # Verify signature
  is_valid = verify_webhook_signature(
    ENV['WICKET_WEBHOOK_SIGNATURE_KEY'],
    raw_body,
    signature
  )

  unless is_valid
    puts 'Invalid webhook signature'
    return [401, 'Invalid signature']
  end

  # Process webhook
  process_webhook(payload)
  [200, 'OK']
end

PHP

<?php

function verifyWebhookSignature($signatureKey, $rawBody, $receivedSignature) {
    // Generate expected signature
    $expectedSignature = hash_hmac('sha256', $rawBody, $signatureKey);

    // Use timing-safe comparison
    return hash_equals($expectedSignature, $receivedSignature);
}

// Laravel example
Route::post('/webhooks/wicket', function (Request $request) {
    $signature = $request->header('X-WicketEvents-Signature');
    $rawBody = $request->getContent();
    $payload = json_decode($rawBody, true);

    // Skip verification for test payloads
    if (isset($payload['test']) && $payload['test'] === true) {
        Log::info('Test payload received');
        return response('OK', 200);
    }

    // Verify signature
    $isValid = verifyWebhookSignature(
        env('WICKET_WEBHOOK_SIGNATURE_KEY'),
        $rawBody,
        $signature
    );

    if (!$isValid) {
        Log::error('Invalid webhook signature');
        return response('Invalid signature', 401);
    }

    // Process webhook
    processWebhook($payload);
    return response('OK', 200);
});
?>

Test Payloads

When you create a webhook endpoint, Wicket sends a test payload with "test": true:

{
  "webhook_delivery_timestamp": "2025-04-05T12:00:00Z",
  "webhook_bundle_uuid": null,
  "events": [],
  "test": true
}

Important: Skip signature verification for test payloads because:

  • The signature_key is only returned after the endpoint is successfully created
  • The test payload is sent before you receive the key
  • Your implementation must handle this by checking payload.test === true
if (payload.test === true) {
  // Skip verification for test payload
  return res.status(200).send('OK');
}

// Verify signature for real payloads
const isValid = verifyWebhookSignature(...);

Security Best Practices

1. Always Verify Signatures

Never skip signature verification in production:

// ✅ Good: Always verify (except test payloads)
if (!payload.test && !verifySignature(...)) {
  return res.status(401).send('Invalid signature');
}

// ❌ Dangerous: Skipping verification
// Never do this in production!

2. Use Timing-Safe Comparison

Use timing-safe comparison functions to prevent timing attacks:

// ✅ Good: Timing-safe
crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b))

// ❌ Avoid: Not timing-safe
a === b

Available in most languages:

  • Node.js: crypto.timingSafeEqual()
  • Python: hmac.compare_digest()
  • Ruby: Rack::Utils.secure_compare()
  • PHP: hash_equals()

3. Use Raw Request Body

Parse the body after verification:

// ✅ Good: Verify raw body, then parse
const rawBody = req.body.toString('utf8');
const isValid = verifySignature(key, rawBody, signature);
if (isValid) {
  const payload = JSON.parse(rawBody);
}

// ❌ Wrong: Parsing before verification
const payload = JSON.parse(req.body);
const isValid = verifySignature(key, JSON.stringify(payload), signature);
// This will likely fail due to JSON formatting differences

4. Store Signature Key Securely

Never hardcode or commit signature keys:

// ✅ Good: Environment variable
const signatureKey = process.env.WICKET_WEBHOOK_SIGNATURE_KEY;

// ✅ Good: Secrets manager
const signatureKey = await secretsManager.getSecret('wicket-webhook-key');

// ❌ Dangerous: Hardcoded
const signatureKey = 'sk_live_abc123...';

5. Reject Invalid Signatures

Return 401 for invalid signatures:

if (!isValid) {
  console.error('Invalid signature detected', {
    endpoint: req.path,
    host: req.headers['x-wicketevents-host']
  });
  return res.status(401).send('Invalid signature');
}

6. Log Security Events

Monitor for suspicious activity:

if (!isValid) {
  logger.security('Invalid webhook signature', {
    ip: req.ip,
    timestamp: new Date().toISOString(),
    host: req.headers['x-wicketevents-host']
  });
}

Common Pitfalls

Parsing Body Before Verification

Problem: JSON parsing changes formatting, breaking signatures

// ❌ Wrong
app.use(express.json()); // Parses body globally
app.post('/webhooks/wicket', (req, res) => {
  const body = req.body; // Already parsed!
  // Can't get raw body for verification
});

Solution: Get raw body for webhook endpoint

// ✅ Correct
app.post('/webhooks/wicket',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body.toString('utf8');
    // Verify with raw body
  }
);

Using Wrong Signature Key

Problem: Using an old or incorrect key

Solution: Verify you saved the key from the creation response

// The signature_key is only returned once:
const response = await createWebhookEndpoint();
const signatureKey = response.data.attributes.signature_key;

// Save it securely immediately!
await saveToSecureStorage('webhook_signature_key', signatureKey);

Not Handling Test Payloads

Problem: Rejecting test payloads during endpoint creation

Solution: Always check for test: true

if (payload.test === true) {
  return res.status(200).send('OK');
}

String vs Buffer Comparison

Problem: Comparing string with buffer fails

// ❌ Wrong
crypto.timingSafeEqual(expectedSignature, receivedSignature);
// TypeError: Input must be a buffer

// ✅ Correct
crypto.timingSafeEqual(
  Buffer.from(expectedSignature),
  Buffer.from(receivedSignature)
);

Testing Verification

Manual Testing

Test your verification logic:

const testSignatureKey = 'test-key-123';
const testBody = '{"test": true}';
const testSignature = crypto
  .createHmac('sha256', testSignatureKey)
  .update(testBody)
  .digest('hex');

// Should return true
const result = verifyWebhookSignature(
  testSignatureKey,
  testBody,
  testSignature
);
console.assert(result === true, 'Verification should pass');

Unit Tests

describe('Webhook signature verification', () => {
  it('should verify valid signatures', () => {
    const key = 'test-key';
    const body = '{"event_type": "people.changed"}';
    const signature = crypto
      .createHmac('sha256', key)
      .update(body)
      .digest('hex');

    expect(verifyWebhookSignature(key, body, signature)).toBe(true);
  });

  it('should reject invalid signatures', () => {
    const key = 'test-key';
    const body = '{"event_type": "people.changed"}';
    const invalidSignature = 'invalid-signature';

    expect(verifyWebhookSignature(key, body, invalidSignature)).toBe(false);
  });

  it('should skip verification for test payloads', () => {
    const payload = { test: true, events: [] };
    // Should not require signature verification
  });
});

Troubleshooting

Signatures Always Fail

Check:

  1. Using correct signature_key (from creation response)
  2. Using raw request body, not parsed JSON
  3. Body encoding is correct (UTF-8)
  4. Not modifying body before verification
  5. Using correct hashing algorithm (HMAC-SHA256)

Test Payloads Rejected

Check:

  • Handling test: true correctly
  • Not requiring signature for test payloads

Intermittent Failures

Check:

  • Request middleware order (get raw body first)
  • Concurrent request handling
  • Body size limits not truncating payloads

On this page