Verifying signatures
How to prove a delivery came from Pengine before you act on it.
Because your endpoint is public, verify the signature before trusting a delivery.
X-Pengine-Signature: sha256=6f2d1c8b4a09e73f5d2b8c1a0e94f7b36d5a2c08e1f4b79d3a6c0e58b2d17f4aThe value after sha256= is the hexadecimal HMAC-SHA256 digest of the exact request body, generated
with your store's API key.
While a rotated key is still in its overlap, the header carries two comma-separated signatures, one for the new key and one for the old key. Accept the delivery if any of them matches:
X-Pengine-Signature: sha256=6f2d1c8b4a09e73f5d2b8c1a0e94f7b36d5a2c08e1f4b79d3a6c0e58b2d17f4a,sha256=0b7e3f9a6c2d58e1f4a07b3c9d6e2f15a8c4b0d7e3f9a62c58e1d4b07a3f9c6eYour API key is the signing secret
There is no separate webhook secret. The same key you send in X-API-Key signs every delivery. When
you rotate it with an overlap, deliveries carry both signatures until the old key expires, so you can
update your webhook receiver and your API caller one after the other. See
Authentication.
The algorithm
Take the raw body
Use the exact request bytes. Parsing and reserializing JSON can change whitespace or key order and invalidate the signature. Configure your framework to preserve the raw body.
Compute the HMAC
Compute an HMAC-SHA256 digest of the raw bytes with your API key, then encode it as hexadecimal. Prefix
the result with sha256=.
Compare in constant time
Compare your result with each signature in the header. Use a constant-time comparison to prevent timing attacks. Do not compare signatures with a plain string equality operator.
Reject what does not match
Return 401 and stop processing. A mismatch indicates an invalid delivery or an undeployed key
rotation.
Code
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
const app = express();
// The raw body is what was signed, so keep it as a Buffer.
app.post('/pengine-webhooks', express.raw({ type: 'application/json' }), (request, response) => {
// During a key rotation overlap, the header carries one signature per key.
const received = (request.get('X-Pengine-Signature') ?? '').split(',');
const expected = Buffer.from('sha256=' + createHmac('sha256', process.env.PENGINE_API_KEY).update(request.body).digest('hex'));
const isValid = received.some((signature) => {
const signatureBytes = Buffer.from(signature);
return signatureBytes.length === expected.length && timingSafeEqual(signatureBytes, expected);
});
if (!isValid) {
return response.status(401).end();
}
const event = JSON.parse(request.body.toString('utf8'));
// Answer first, work afterwards.
response.status(200).end();
void enqueue(event);
});What the signature does not do
The signature proves that Pengine sent the body and that it was not modified. It does not include a timestamp, so a replayed request still passes verification.
Use both of these safeguards:
- Deduplicate on the event
id. Ignore IDs you have already processed. This also handles standard webhook retries. - Refetch the resource. Acting on the current state of an order rather than on the payload makes a stale delivery harmless.