Webhooks

Each request carries a CPaaS-Signature header (hex) and a CPaaS-Timestamp (unix seconds). Compute the HMAC over {timestamp}.{raw_body}. Use a constant-time compare and reject stale timestamps to prevent replay.

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

const app = express();
const SIGNING_SECRET = process.env.CPAAS_WEBHOOK_SECRET!;

app.post(
  '/webhooks/cpaas',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('CPaaS-Signature') ?? '';
    const timestamp = req.header('CPaaS-Timestamp') ?? '';
    const payload   = req.body.toString('utf8');

    const skew = Math.abs(Date.now() / 1000 - Number(timestamp));
    if (skew > 300) return res.status(400).send('stale timestamp');

    const expected = crypto
      .createHmac('sha256', SIGNING_SECRET)
      .update(`${timestamp}.${payload}`)
      .digest('hex');

    const ok = crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex'),
    );
    if (!ok) return res.status(400).send('invalid signature');

    const event = JSON.parse(payload);
    handleEvent(event);

    res.status(200).send('ok');
  },
);

A non-2xx response or timeout after 10 seconds triggers a retry with exponential backoff and jitter. After 8 failed attempts (~24 hours) the delivery lands in the endpoint's dead-letter queue where it can be replayed from the dashboard.

Testing webhooks

Use the built-in tester to send synthetic events with a real signature to your endpoint — inspect deliveries, response bodies, and timing without touching production data.