Verify Signatures
Your webhook endpoint is a public URL, so anyone who finds it can send it requests. Without a check, someone could send a fake webhook, such as a transfer.status.completed for a transfer that never happened, and trick your system into releasing goods or funds.
To prevent this, Harbor signs every webhook it sends with your subscription's secret, and puts the signature in the harbor-signature header. Only Harbor and you know the secret. By checking the signature, you confirm that:
- The request came from Harbor, not from someone else.
- The payload wasn't changed on the way.
If the signature doesn't match, ignore the request.
You need three things:
- The raw request body, exactly as received
- The
harbor-signatureheader - Your signing secret: the
callback_secretreturned when you create the subscription
The Signature Header
The header has two parts, separated by a comma:
harbor-signature: t=1791185782,v1=e063df0ff20831c3591e4cec29bb775cd9da0f7afde4a584bb8d4f1cbbbbc598
tis the timestamp.v1is the signature, an HMAC-SHA256 hash in hex.
How to Verify
- Split the header on
,and then on=, to gettandv1. - Build the signed payload: the timestamp, a
., then the raw request body. For example,1791185782.{"uuid":"transfer_...",...}. - Compute the HMAC-SHA256 of the signed payload, using your
callback_secretas the key. Encode it as hex. - Compare your result with
v1. If they match, the webhook is from Harbor.
Use the raw body
Sign the body exactly as you received it. If you parse the JSON and convert it back to a string, the spacing can change and the signature won't match.
Node.js Example
This example uses Express. express.raw() keeps the body as raw bytes, so the signature can be checked.
const crypto = require('crypto');
const express = require('express');
const app = express();
const SIGNING_SECRET = process.env.HARBOR_CALLBACK_SECRET; // your callback_secret
function verifyHarborSignature(rawBody, signatureHeader, secret) {
// 1. Split the header into t and v1
const parts = Object.fromEntries(
signatureHeader.split(',').map((part) => part.split('=', 2))
);
const timestamp = parts.t;
const signature = parts.v1;
if (!timestamp || !signature) return false;
// 2 and 3. Compute the HMAC-SHA256 of "timestamp.rawBody"
const expected = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
// 4. Compare the two signatures
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(signature, 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString('utf8');
const signatureHeader = req.get('harbor-signature') || '';
if (!verifyHarborSignature(rawBody, signatureHeader, SIGNING_SECRET)) {
return res.status(400).send('Invalid signature');
}
const event = JSON.parse(rawBody);
console.log('Received', event.event);
res.sendStatus(200); // Reply within 10 seconds
});
app.listen(3000);crypto.timingSafeEqualcompares the signatures safely, without leaking timing information.- Return a
2xxquickly. Do any slow work after you reply.
When to Verify
Verify every webhook, especially before you act on it. For example, check the signature of a transfer.status.completed webhook before you deliver goods or release funds.
Updated about 1 month ago