Tutorial · Security

Webhook timestamp security

Replay attacks

An attacker who captures a valid signed webhook can replay it until the signature scheme or timestamp expires. Signing only the body without time lets replays live forever. Include the timestamp in the signed bytes (e.g.t.payload concatenation) so tampering one field invalidates the MAC.

Five-minute tolerance

Cloud load balancers may buffer requests; use server time from NTP-synced nodes. Mobile gateways sometimes batch deliveries — measure real skew from partners before tightening tolerances below 60s.

Express middleware example

import express from 'express';
import crypto from 'crypto';

const TOLERANCE_SEC = 300;

function verifyWebhook(req, res, next) {
  const sig = req.header('X-Signature');
  const ts = req.header('X-Timestamp');
  const body = req.rawBody; // capture in json verify middleware
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(ts)) > TOLERANCE_SEC) {
    return res.status(400).send('stale timestamp');
  }
  const hmac = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET);
  hmac.update(`${ts}.${body}`);
  const expected = hmac.digest('hex');
  const ok = crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
  if (!ok) return res.status(401).send('bad signature');
  return next();
}

Testing and skew

Unit tests should freeze time with libraries like Sinon or move clock manually. Integration tests must send headers slightly in the past within tolerance. When skew exceeds tolerance, return a distinct error code so ops can distinguish bad clocks from bad secrets without leaking internals to attackers.

Key takeaways

• Timestamp + signature + constant-time compare — missing any piece fails the model.
• Persist processed event ids with TTL > tolerance to drop duplicates.
• Rotate shared secrets periodically; dual-sign during migration if feasible.
• Document partner clock requirements in onboarding PDFs.
• See also session timestamps for related auth math.