Verify signatures

Every tool call and post-call webhook is signed with the agent’s signing secret, the Standard Webhooks way. Find the secret on the agent’s Webhook tab. It starts with whsec_, and each agent has its own.

Headers

Header	Value
`webhook-id`	A unique message ID
`webhook-timestamp`	Seconds since the epoch
`webhook-signature`	`v1,` + the base64 HMAC-SHA256 signature

The signature is computed over {webhook-id}.{webhook-timestamp}.{body}, keyed with the base64-decoded part of the secret after whsec_.

With a library (recommended)

Standard Webhooks libraries check the signature and refuse requests more than 5 minutes old.

// npm install standardwebhooks
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.AGENT_SIGNING_SECRET); // whsec_…
// Throws if the signature is wrong or the request is too old
const payload = webhook.verify(rawBody, request.headers);

# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

webhook = Webhook(os.environ["AGENT_SIGNING_SECRET"])  # whsec_…
payload = webhook.verify(raw_body, headers)

Libraries exist for many other languages too: see standardwebhooks.com.

By hand

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // older than 5 minutes

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");

  return headers["webhook-signature"].split(" ").some((part) => {
    const [version, signature] = part.split(",");
    return version === "v1" && signature?.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  });
}

Common mistakes

Verifying the parsed body. Use the raw request body, exactly as received. Re-serialised JSON won’t match.
Using another agent’s secret. Each agent has its own.
After rotating. Calls that start after you click Rotate secret use the new secret; calls already in progress keep the old one until they end. Accept both briefly while you update your servers.

Overview

Realtime avatar API

Private agent links

Requests we send you

Headers

With a library (recommended)

By hand

Common mistakes

​Headers

​With a library (recommended)

​By hand

​Common mistakes

Headers

With a library (recommended)

By hand

Common mistakes