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.mjs

Expect 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.