Verifying signatures

Every delivery is signed so you can prove it came from Vocily and wasn’t replayed. Verify every request before acting on it.

The signature

Every delivery carries two headers:

Vocily-Timestamp: 1730000000000
Vocily-Signature: t=1730000000000,v1=1be13707222ef2ff263ac7e7a0e26d53f454ca2380c090736ae156b1ac9986c9

The Vocily-Signature header is a comma-separated list of key=value parts:

Part	Meaning
`t`	The Unix-millisecond timestamp when we signed the request. It’s also baked into the signed string, so it can’t be tampered with.
`v1`	The signature: `HMAC-SHA256(secret, "<t>." + rawBody)`, hex-encoded. `v1` = “version 1 of the signing scheme” — the value after it is the actual digest you recompute and compare.

Where secret is the signing secret you set on the endpoint and rawBody is the exact bytes we sent (see the warning below).

v1 can appear more than once. During a secret rotation we send one v1 per active secret (old + new), e.g. t=…,v1=<old>,v1=<new>. Your verifier should accept if any v1 matches, so both secrets work until the rotation grace window closes — zero dropped webhooks. The v1 prefix also lets us add a future scheme (v2=…) later without breaking existing receivers.

How to verify

Read the RAW body

Use the exact received bytes. Do not re-serialize parsed JSON — key order, whitespace, and escaping change the bytes and the signature will never match.

Parse the header

Split Vocily-Signature into t and one or more v1 values.

Reject stale timestamps

If |now − t| > 300000 ms (5 minutes), drop it — this blocks replay of a captured delivery.

Recompute and compare

Compute HMAC-SHA256(secret, "<t>." + rawBody) and constant-time compare against each v1. Accept if any matches (during a secret rotation we send two v1 values so old and new both verify).

Always compare in constant time (hmac.compare_digest, crypto.timingSafeEqual, hash_equals) — never == on the hex string.

Examples

import hashlib, hmac, time

TOLERANCE_MS = 300_000

def verify(raw_body: bytes, signature_header: str, secret: str, now_ms: int | None = None) -> bool:
    ts, v1s = None, []
    for part in signature_header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            ts = int(value)
        elif key == "v1":
            v1s.append(value)
    if ts is None or not v1s:
        return False
    now_ms = int(time.time() * 1000) if now_ms is None else now_ms
    if abs(now_ms - ts) > TOLERANCE_MS:
        return False
    signed = f"{ts}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, v1) for v1 in v1s)

const crypto = require("crypto");
const TOLERANCE_MS = 300_000;

function verify(rawBody, signatureHeader, secret, nowMs = Date.now()) {
  let ts = null;
  const v1s = [];
  for (const part of signatureHeader.split(",")) {
    const [k, v] = part.trim().split("=");
    if (k === "t") ts = parseInt(v, 10);
    else if (k === "v1") v1s.push(v);
  }
  if (ts === null || v1s.length === 0) return false;
  if (Math.abs(nowMs - ts) > TOLERANCE_MS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.`)
    .update(rawBody) // rawBody must be the exact received bytes (Buffer/string)
    .digest("hex");
  const exp = Buffer.from(expected);
  return v1s.some((v1) => {
    const buf = Buffer.from(v1);
    return buf.length === exp.length && crypto.timingSafeEqual(buf, exp);
  });
}

Frameworks that give you parsed JSON by default (e.g. Express) need the raw body. In Express, use express.raw({ type: "application/json" }) on the webhook route and verify before parsing.

Test vector

Before you go live, confirm your code is correct against this known-answer test — fixed inputs with the exact v1 they must produce. No live webhook needed. (Example secret; don’t use it in production.)

secret : whsec_docs_example_do_not_use
t      : 1730000000000
body   : {"event_id":"evt_docexample","event_type":"call.ended"}
signed : 1730000000000.{"event_id":"evt_docexample","event_type":"call.ended"}
v1     : 1be13707222ef2ff263ac7e7a0e26d53f454ca2380c090736ae156b1ac9986c9

signed is the exact string that gets hashed: "<t>." + body.
v1 is the expected result: HMAC-SHA256(secret, signed) in hex.

Check your implementation

Feed the vector into the verify() from above: build the header as t=<t>,v1=<v1>, pass the raw body, and set now = t (so the fixed old timestamp doesn’t trip the 5-minute freshness check). It must return true for the real body and false for a tampered one.

raw_body = b'{"event_id":"evt_docexample","event_type":"call.ended"}'
header   = "t=1730000000000,v1=1be13707222ef2ff263ac7e7a0e26d53f454ca2380c090736ae156b1ac9986c9"
secret   = "whsec_docs_example_do_not_use"

assert verify(raw_body, header, secret, now_ms=1730000000000) is True            # correct implementation
assert verify(raw_body + b"x", header, secret, now_ms=1730000000000) is False    # detects tampering

const rawBody = '{"event_id":"evt_docexample","event_type":"call.ended"}';
const header  = "t=1730000000000,v1=1be13707222ef2ff263ac7e7a0e26d53f454ca2380c090736ae156b1ac9986c9";
const secret  = "whsec_docs_example_do_not_use";

console.assert(verify(rawBody, header, secret, 1730000000000) === true);          // correct implementation
console.assert(verify(rawBody + "x", header, secret, 1730000000000) === false);   // detects tampering

If the first line passes, your HMAC logic is correct and you’re ready for live deliveries. If it fails, check the two most common bugs: re-serializing the JSON instead of using the raw bytes, and the exact "<t>." + body format of the signed string.

No-code hosts

Zapier, Make, n8n, and similar “catch hook” tools usually can’t compute HMAC, so they can’t verify the signature — the authenticity layer is decorative there. Fine for prototypes; for anything sensitive, point Vocily at your own server and verify.

Calls

Agents

Webhooks

Verifying signatures

The signature

How to verify

Examples

Test vector

Check your implementation

No-code hosts

​The signature

​How to verify

​Examples

​Test vector

​Check your implementation

​No-code hosts

The signature

How to verify

Examples

Test vector

Check your implementation

No-code hosts