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
-
Wicket generates a signature by creating an HMAC-SHA256 hash of the request body using your endpoint's
signature_key -
The signature is sent in the
X-WicketEvents-Signatureheader with each webhook request -
Your server verifies by generating the same HMAC-SHA256 hash and comparing it
-
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/jsonX-WicketEvents-Signature: HMAC-SHA256 hex digest for verificationX-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']
endPHP
<?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_keyis 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 === bAvailable 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 differences4. 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:
- Using correct
signature_key(from creation response) - Using raw request body, not parsed JSON
- Body encoding is correct (UTF-8)
- Not modifying body before verification
- Using correct hashing algorithm (HMAC-SHA256)
Test Payloads Rejected
Check:
- Handling
test: truecorrectly - 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