Skip to content

Verify signatures

View as Markdown

Every request is signed with your webhook secret. Verify the signature before you trust the body.

Header Description
X-YAA-Webhook-Id The event ID. It stays the same when we retry an event.
X-YAA-Webhook-Signature Base64-encoded HMAC-SHA256 signature.
X-YAA-Webhook-Signature-Timestamp Unix time in seconds when we sent this attempt.
  1. Read the three headers above.

  2. Build the signed message by joining the ID, the timestamp and the raw request body with periods:

    {X-YAA-Webhook-Id}.{X-YAA-Webhook-Signature-Timestamp}.{raw body}
  3. Compute the HMAC-SHA256 of that message with your webhook secret as the key.

  4. Base64-encode the result.

  5. Compare it to X-YAA-Webhook-Signature with a constant-time comparison.

  6. Reject the request if the timestamp is more than 5 minutes old.

const crypto = require('crypto');
const express = require('express');
const app = express();
function isValidSignature(secret, id, timestamp, rawBody, signature) {
const expected = crypto
.createHmac('sha256', secret)
.update(`${id}.${timestamp}.${rawBody}`)
.digest();
const received = Buffer.from(signature, 'base64');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
// express.raw keeps the body as bytes so it can be verified.
app.post('/webhooks/accountable', express.raw({ type: 'application/json' }), (req, res) => {
const id = req.get('X-YAA-Webhook-Id');
const signature = req.get('X-YAA-Webhook-Signature');
const timestamp = req.get('X-YAA-Webhook-Signature-Timestamp');
if (!id || !signature || !timestamp) return res.status(400).send('Missing signature headers');
const age = Math.floor(Date.now() / 1000) - Number(timestamp);
if (Number.isNaN(age) || age > 300) return res.status(400).send('Stale timestamp');
const rawBody = req.body.toString('utf8');
if (!isValidSignature(process.env.YAA_WEBHOOK_SECRET, id, timestamp, rawBody, signature)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(rawBody);
// Queue the event for processing, then respond.
res.sendStatus(200);
});

Check your code against these fixed values. They are also in /test-vectors/webhook-signature.json.

Input Value
Secret 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
X-YAA-Webhook-Id breathalyzer_665f1c2ab7e4d90012a3f4c1_1767225600000_k3x9q2a
X-YAA-Webhook-Signature-Timestamp 1767225600

The raw body, with no spaces or line breaks:

{"event_type":"breathalyzer.result.deleted","data":{"test_id":"665f1c2ab7e4d90012a3f4c3"}}

Your code should compute this signature:

AlssRB6xfuj0mWw9X2XTPipmFP7/P+hAhhykmdI6Bdc=

The timestamp is January 1, 2026. Skip the 5 minute check when you test with these values.

  • Store the secret in a secret manager or an environment variable. Keep it out of source control.
  • Each webhook has its own secret.
  • To replace a secret, use Rotate Secret in the dashboard. The old secret stops working right away.