Skip to main content
flag
Mon - Fri   10:00 – 18:00

Verifying webhook signatures

API Documentation / Voice Broadcast / Verifying webhook signatures

Base URL for your account: https://cpaas.studio

POST https://your-server.example/your-webhook (we call you)

Every webhook we send is signed with your account's webhook signing secret, so you can check it came from us and was not replayed. Find, reveal, copy and regenerate the secret on Administration → API Keys → Webhook signing secret.

Regenerating the secret takes effect immediately — there is no grace period. Update your receivers right after you regenerate it, or they will reject our requests.

Parameters

Param Type Required Notes
X-CPaaS-Timestamp header, unix seconds yes When we sent this attempt. A retry has a new value.
X-CPaaS-Signature header yes sha256=<hex HMAC-SHA256 of "{X-CPaaS-Timestamp}.{raw body}" with your secret>.
X-CPaaS-Event-Id header yes The event_id from the body — de-duplicate on it.

Request example

<?php
// Use the RAW body — not a re-encoded json_decode() result.
$body   = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_X_CPAAS_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_X_CPAAS_SIGNATURE'] ?? '';
$secret = getenv('CPAAS_WEBHOOK_SECRET'); // whsec_...

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);

// Constant-time compare + 5-minute replay window (either direction).
if (! ctype_digit($ts) || abs(time() - (int) $ts) > 300 || ! hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
http_response_code(200);
// Express — keep the raw body: express.raw(), not express.json().
const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/your-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-CPaaS-Timestamp') || '';
  const sig = req.get('X-CPaaS-Signature') || '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.CPAAS_WEBHOOK_SECRET) // whsec_...
    .update(`${ts}.${req.body}`)
    .digest('hex');

  const fresh = /^\d+$/.test(ts) && Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
  const same = sig.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));

  if (!fresh || !same) return res.sendStatus(401);

  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

Success response (data)

{
    "headers": {
        "X-CPaaS-Timestamp": "1762683341",
        "X-CPaaS-Signature": "sha256=6f0c1e9a4b7d2c58e3a1f09b7c64d2e8a5b3c1f07e9d2a46b8c0e3f5a7d9b1c2",
        "X-CPaaS-Event-Id": "0b6f1d2e-8c4a-4f7e-9a51-3c2d7e9b1f40"
    },
    "body": {
        "event": "voice.broadcast.status",
        "event_id": "0b6f1d2e-8c4a-4f7e-9a51-3c2d7e9b1f40",
        "request_id": "BCQVCUU6YTAA",
        "call_id": "BCQVCUU6YTAA-1",
        "number": "9876543210",
        "status": "answered",
        "duration": 32,
        "answered_at": "2026-11-09T10:15:04+00:00",
        "reference": "order-4471",
        "custom_param": "crm-lead-88231",
        "timestamp": "2026-11-09T10:15:41+00:00"
    }
}

Notes

  • Signed string: the X-CPaaS-Timestamp value, a dot, then the raw request body exactly as received — e.g. 1762683341.{"event":"voice.broadcast.status",...}.
  • Compute HMAC-SHA256 with the whole secret (including the whsec_ prefix) as the key, hex-encode it, prefix sha256= and compare with X-CPaaS-Signature in constant time (hash_equals / crypto.timingSafeEqual).
  • Reject requests whose X-CPaaS-Timestamp is more than 5 minutes (300 seconds) from your clock. The signature covers the timestamp, so it cannot be changed — the window stops an old captured request being re-sent. Keep your clock NTP-synced.
  • Verify over the raw bytes. Parsing the JSON and encoding it again can change spacing or escaping and break the signature.
  • Rotation is immediate: after Regenerate, only the new secret verifies. There is one secret per account, shared by all its webhooks.
  • webhook_param still works as an extra correlation token of your own (returned as custom_param).
  • WhatsApp webhooks with their own signing secret set on WhatsApp → Channels → Webhooks are signed with that secret instead.

Need more context? See Getting started for authentication, the response envelope, and the full error-code reference.