Verify signatures
Check the webhook-signature header and timestamp in Node.js, Python, PHP or Go, so you only trust webhooks that CallMitra sent.
Every delivery to a webhook endpoint is signed with that endpoint's secret. Check the signature before you trust the body. The scheme follows the Standard Webhooks specification.
How the signature works
Each delivery has three headers:
| Header | Example |
|---|---|
webhook-id | evt_5f0c6a1e9b2d4c7e8a1f3b5d7c9e0a2b |
webhook-timestamp | 1763184730 (Unix seconds, new on each attempt) |
webhook-signature | v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= |
CallMitra computes the signature like this:
- Key: take your secret (
whsec_MfKQ…), remove thewhsec_prefix, and base64-decode the rest. The result is 32 bytes. - Signed content: the
webhook-id, a dot, thewebhook-timestamp, a dot, then the raw request body:{webhook-id}.{webhook-timestamp}.{body}. - Signature: HMAC-SHA256 of the signed content with the key, base64-encoded (standard alphabet, with padding), prefixed with
v1,.
webhook-signature can hold more than one signature, separated by spaces. For 24 hours after you rotate the secret, it holds one from the new secret and one from the old secret. Accept the request if any v1 signature matches.
Steps
Read the raw body
Use the body bytes exactly as received. Do not parse and re-serialize the JSON first: any change in spacing or key order breaks the signature.
Check the timestamp
Reject the request if webhook-timestamp is more than 5 minutes away from your clock. This stops someone replaying a captured request later.
Compute and compare
Compute the expected signature as above. Compare it with each v1, entry in webhook-signature using a constant-time comparison. If none match, answer 401.
Drop duplicates
Skip the event if you already handled its webhook-id. Retries and redeliveries reuse it.
Examples
Each example reads the secret from CALLMITRA_WEBHOOK_SECRET.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
const SECRET = process.env.CALLMITRA_WEBHOOK_SECRET; // whsec_...
const KEY = Buffer.from(SECRET.replace(/^whsec_/, ''), 'base64');
const TOLERANCE_S = 300;
function verify(rawBody, headers) {
const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
const sigHeader = headers['webhook-signature'];
if (!id || !sigHeader || !/^\d+$/.test(ts ?? '')) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > TOLERANCE_S) return false;
const expected = crypto
.createHmac('sha256', KEY)
.update(`${id}.${ts}.`)
.update(rawBody)
.digest();
return sigHeader.split(' ').some((entry) => {
const [version, sig] = entry.split(',');
if (version !== 'v1' || !sig) return false;
const received = Buffer.from(sig, 'base64');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
// express.raw keeps the body as a Buffer, so the bytes are unchanged.
app.post('/webhooks/callmitra', express.raw({ type: 'application/json' }), (req, res) => {
if (!verify(req.body, req.headers)) return res.sendStatus(401);
const event = JSON.parse(req.body.toString('utf8'));
// Skip event.id if you have already handled it, then queue the work.
res.sendStatus(204);
});Use a Standard Webhooks library
Because the scheme follows Standard Webhooks, the official libraries verify CallMitra deliveries too. For example, standardwebhooks on npm and PyPI. See github.com/standard-webhooks/standard-webhooks for other languages. Pass the whole whsec_… secret, the raw body and the request headers.
from standardwebhooks.webhooks import Webhook
wh = Webhook(os.environ["CALLMITRA_WEBHOOK_SECRET"])
event = wh.verify(raw_body, request.headers) # raises if the signature or timestamp is wrongTest your receiver
Call POST /api/v1/webhook-endpoints/{endpoint_id}/test. It sends a signed webhook.test event and returns your server's status code and the first 1 KB of its answer. A 401 there usually means one of the mistakes below.
Common mistakes
- Verifying parsed JSON. Frameworks that parse the body first (for example
express.json()) lose the original bytes. Use the raw body. - Using the secret as text. The HMAC key is the base64-decoded part after
whsec_, not the secret string itself. - Checking only the first signature. After a rotation the header has two. Split on spaces and try each one.
- Plain string comparison.
==leaks timing information. Use the constant-time helpers shown above. - Wrong endpoint's secret. Each endpoint has its own secret.
- Clock drift. The 5-minute window assumes your server clock is in sync (NTP).
The X-Signature-SHA256 header
Deliveries to webhook endpoints also carry X-Signature-SHA256, so a receiver built for campaign and agent webhooks keeps working. Prefer webhook-signature: it covers the id and timestamp, and it supports secret rotation. If you do check X-Signature-SHA256 on an endpoint delivery, see Verify X-Signature-SHA256 for the key it uses and how to check replays.