Introduction

Vouch Webhooks enable callbacks to be made to your HTTP endpoints whenever specific events have been triggered (often referred to as notifications) within the Vouch Platform.

Vouch Webhooks are available for customers who hold an Enterprise Vouch plan.

Setup Webhook

Vouch allows brands to specify one webhook URL where all events will be sent to. This can be setup within the Developer settings page within the Vouch Admin User Interface.

Webhook Secret

When your secret token is set, Vouch uses it to create a hash signature with each payload. This hash signature is included with the headers of each request as X-Vouch-Signature

The intention is to calculate a hash using your Secret Key, and ensure that the result matches the hash from Vouch.

Vouch uses an HMAC hex digest to compute the hash. To validate the hash, the following code could be used.

const { createHmac, timingSafeEqual } = await import('crypto');

const secret = 'I-love-secret';

function assertSignature({secret, signature, payload}) {
    const [algorithm, _signature] = (signature).toString().split('=');
    if (!_signature) {
        return false;
    }
    const selfSignedSignature = createHmac(algorithm, secret)
        .update(payload).digest('hex');
    return timingSafeEqual(Buffer.from(_signature), Buffer.from(selfSignedSignature));
}

app.use('/webhook', (req, res) => {
  const { headers, body: payload } = req;
  const signature = headers['x-vouch-signature'];
  if (!assertSignature({secret, signature, payload: JSON.stringify(payload)})) {
    return res.status(401).send('Not authenticate');
  }
  res.status(200).send('ok');
});

Using a plain == or === operator is not advised. A method like secure_compare performs a "constant time" string comparison, which helps mitigate certain timing attacks against regular equality operators.