Webhooks Overview

{
  "webhookType": "WEBHOOK_TYPE",
  "upstreamEntityId": "507f1f77bcf86cd799439010",
  "payload": { ... }
}

{
  "status": "received",
  "processedAt": "2024-01-15T14:22:05Z"
}

import { createHmac, timingSafeEqual } from 'node:crypto';

const MAX_AGE_SECONDS = 300; // 5 minutes

function verifyWebhookSignature(rawBody, signature, timestamp, hexSecret) {
  // Reject anything missing or of the wrong type BEFORE decoding. A request with no
  // signature header reaches this function as `undefined`, and `Buffer.from(undefined,
  // 'hex')` throws `ERR_INVALID_ARG_TYPE`, so skipping this check turns an unsigned
  // request into a 500 instead of the 401 it should get.
  if (typeof signature !== 'string' || typeof timestamp !== 'string' || typeof hexSecret !== 'string') return false;
  if (typeof rawBody !== 'string' || signature.length === 0) return false;

  // Reject stale requests next. Without this the signature check alone accepts a
  // captured request replayed any number of times, because those bytes are genuine.
  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > MAX_AGE_SECONDS) return false;

  const signedContent = `${timestamp}.${rawBody}`;
  const expectedSignature = createHmac('sha256', Buffer.from(hexSecret, 'hex')).update(signedContent).digest('hex');

  const received = Buffer.from(signature, 'hex');
  const expected = Buffer.from(expectedSignature, 'hex');

  // timingSafeEqual throws on a length mismatch, so check that first. A wrong-length
  // signature is a malformed request, not a valid one.
  if (received.length !== expected.length) return false;

  // Timing-safe comparison, so a wrong signature cannot be guessed byte by byte
  return timingSafeEqual(received, expected);
}

// Example: Express.js webhook endpoint
// Use the verify callback to capture the raw body buffer before JSON parsing
app.post(
  '/webhook',
  express.json({
    verify: (req, _res, buf) => {
      req.rawBody = buf.toString('utf8');
    },
  }),
  (req, res) => {
    const signature = req.headers['x-turris-signature'];
    const timestamp = req.headers['x-turris-timestamp'];

    const isValid = verifyWebhookSignature(req.rawBody, signature, timestamp, process.env.TURRIS_CLIENT_SECRET);

    if (!isValid) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    console.log('Received webhook:', req.body.webhookType);
    console.log('Payload:', req.body.payload);

    res.status(200).json({ status: 'received' });
  },
);