Webhooks

{
  "id": "event_3f9a1c8b2d...",
  "event": "person.created",
  "version": "v1",
  "created_at": "2026-05-26T14:00:00.000Z",
  "person": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "full_name": "Anna Reed",
    "email": { "1": "anna@acme.com" },
    "created_at": "2026-05-26T14:00:00Z"
  }
}

Webhook-Signature: sha256=<hex>

const crypto = require('crypto');

function isValidSignature(rawBody, receivedSignature, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(receivedSignature), Buffer.from(expected));
}

// Express: read raw bytes before any JSON parsing
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['webhook-signature'];
  if (!sig || !isValidSignature(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const payload = JSON.parse(req.body);
  res.sendStatus(200);
  processEvent(payload); // async, after responding
});

import hmac, hashlib

def is_valid_signature(raw_body: bytes, received: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received, expected)

async function handleWebhook(payload) {
  if (await db.events.findOne({ id: payload.id })) return;
  await db.events.insert({ id: payload.id, processedAt: new Date() });
  await processEvent(payload);
}