Verify signatures

Check that a delivery really came from Telleo and was not changed.

Your endpoint is public, so anyone could post to it. Every delivery from Telleo is signed with your webhook secret; check the signature before you trust the body.

The signature header

Telleo-Signature: t=1760348000,v1=5b0c3f…e91a

• t: when the delivery was signed, in Unix seconds.
• v1: the hex HMAC-SHA256 of t + "." + <raw request body>, keyed with your webhook secret.

To verify:

1. Read the raw request body, exactly as received. Do not parse and re-serialise the JSON first: any change in spacing or key order changes the signature.
2. Compute HMAC-SHA256(secret, t + "." + raw_body) as lowercase hex.
3. Compare it with v1 using a constant-time comparison.
4. Reject the request if t is more than 5 minutes from your clock. This stops someone replaying an old delivery.

Examples

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.TELLEO_WEBHOOK_SECRET;

// express.raw keeps the exact bytes Telleo signed.
app.post("/telleo/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Telleo-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${parts.t}.${req.body}`)
    .digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - t) < 300;
  const valid =
    parts.v1 &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!fresh || !valid) return res.status(400).send("bad signature");

  const event = JSON.parse(req.body);
  res.sendStatus(200); // answer first
  handleEvent(event);  // then do the work
});

Rotating the secret

New secret in the dashboard, or POST /v1/webhook/rotate-secret, returns a new secret once and signs every later delivery with it. To rotate without failing deliveries:

1. Make your endpoint accept a signature made with either the old or the new secret.
2. Rotate, and store the new secret.
3. After a few minutes, remove the old secret.

Other headers

Header	Value
Telleo-Event-Id	The event id; the same on every retry.
Telleo-Event-Type	call.completed, call.not_connected or webhook.test.
User-Agent	Telleo-Webhooks/1.0
Content-Type	application/json