Test webhook signatures locally EN
Run five synthetic tests before connecting a webhook receiver to a store.
This exercise uses Node.js built-in modules on your own computer. It opens no server, contacts no store and creates no subscription, order or payment. You need neither an API key nor customer data.
A valid signature proves that the received bytes match the signature for the chosen secret. It does not prove the event is new, authorize an action in your receiving system or ensure that work happens only once.
1. Create a local test file
Save the following as webhook-signature.test.mjs. The fixed secret is synthetic
test data, not a credential to use in a real subscription. The example follows
Kaduno's HMAC-SHA256 format with sha256= followed by a hexadecimal digest.
import { createHmac, timingSafeEqual } from 'node:crypto';
import assert from 'node:assert/strict';
import test from 'node:test';
function verifyWebhook(rawBody, signature, secret) {
if (!Buffer.isBuffer(rawBody) || typeof signature !== 'string' || !secret) {
return false;
}
const expected = Buffer.from(
'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex'),
);
const received = Buffer.from(signature);
return expected.length === received.length && timingSafeEqual(expected, received);
}
const secret = 'LOCAL_TEST_ONLY_NOT_A_PRODUCTION_SECRET';
const rawBody = Buffer.from(
'{"event":"order.placed","deliveryId":"local-example-1","payload":{"id":"synthetic-order"}}',
);
const signature = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
test('accepts original bytes and correct signature', () => {
assert.equal(verifyWebhook(rawBody, signature, secret), true);
});
test('rejects changed data', () => {
const changed = Buffer.from(rawBody.toString().replace('synthetic-order', 'changed-order'));
assert.equal(verifyWebhook(changed, signature, secret), false);
});
test('rejects reserialization of equivalent JSON', () => {
const reformatted = Buffer.from(JSON.stringify(JSON.parse(rawBody), null, 2));
assert.equal(verifyWebhook(reformatted, signature, secret), false);
});
test('rejects missing signature, bad length and wrong secret', () => {
assert.equal(verifyWebhook(rawBody, undefined, secret), false);
assert.equal(verifyWebhook(rawBody, 'sha256=short', secret), false);
assert.equal(verifyWebhook(rawBody, signature, 'wrong-secret'), false);
});
test('a repeated delivery still has a valid signature', () => {
assert.equal(verifyWebhook(rawBody, signature, secret), true);
assert.equal(verifyWebhook(rawBody, signature, secret), true);
});2. Run without contacting the store
Use a supported Node.js release with the built-in test runner. No packages need to be installed.
node --test webhook-signature.test.mjsExpect five passing tests and zero failures. Output formatting can vary by Node.js version. If a test fails, check the file and raw-body handling before continuing; do not disable signature verification.
3. Understand what this does not test
The last test deliberately accepts the same signed message twice.
A valid signature is not replay protection. Use the delivery ID as a unique
key in durable storage and record receipt and planned work atomically. An
in-memory Set is not enough across restarts or multiple processes.
This exercise does not test an HTTP server, HTTPS, your framework's raw request body handling, durable queues, failures or actual Kaduno delivery. It is not a production-ready receiver. Re-encoding parsed JSON changes the bytes being checked.
4. Agree a controlled integration test
Before connecting a receiver, agree the test store, signing secret and permitted outbound effects. Check invalid signatures, repeated and concurrent delivery, restarts after receipt, unexpected event types and rejection of work for the wrong store. Do not use real customer orders or payments to try the example.
The Norwegian receiver guide covers
subscriptions, delivery logs and retries. Use the
read-only API quickstart for limited API
access. Store the real signing secret in secure receiver configuration, not source
code, screenshots or support tickets. A REST webhook subscription requires
webhooks:manage; a delivery without a configured signing secret is not signed.