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-signature header
  • Your signing secret: the callback_secret returned when you create the subscription

The Signature Header

The header has two parts, separated by a comma:

harbor-signature: t=1791185782,v1=e063df0ff20831c3591e4cec29bb775cd9da0f7afde4a584bb8d4f1cbbbbc598
  • t is the timestamp.
  • v1 is the signature, an HMAC-SHA256 hash in hex.

How to Verify

  1. Split the header on , and then on =, to get t and v1.
  2. Build the signed payload: the timestamp, a ., then the raw request body. For example, 1791185782.{"uuid":"transfer_...",...}.
  3. Compute the HMAC-SHA256 of the signed payload, using your callback_secret as the key. Encode it as hex.
  4. 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.timingSafeEqual compares the signatures safely, without leaking timing information.
  • Return a 2xx quickly. 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.


Did this page help you?