Validating webhook signatures

Anyone who learns your webhook URL can send requests to it. Callers signs its requests so your server can confirm they’re genuine and weren’t modified on the way. Verify the signature before you trust or act on a request. Callers uses two signing schemes, depending on what sent the request:

Request	Header	Algorithm	Encoding	Verify with
Simple webhooks (Voice agents)	`X-Signature`	RSA-SHA256	Base64	The Callers public key (below)
Custom webhooks (Create Custom Webhook) and HTTP actions	`X-Signature` and `X-Signature-Type: HMAC`	HMAC-SHA256	Hex	Your account’s HMAC secret
Custom webhooks and HTTP actions with Sign with RSA-SHA256 on	`X-Signature` and `X-Signature-Type: RSA`	RSA-SHA256	Base64	The Callers public key (below)

If a request has X-Signature-Type, use it to pick the scheme. If it doesn’t, it’s a simple webhook: use RSA.

Always verify against the raw request body, exactly as received, before parsing it. Parsing JSON and serializing it again can change spacing, key order, or number formatting and break the signature.

Simple webhooks: RSA-SHA256

Callers signs the exact JSON body of each simple webhook with its private key (RSA, PKCS #1 v1.5 padding, SHA-256) and sends the base64 signature in X-Signature. You verify it with the public key.

Callers public key

Save this key in your application, for example as callers-public-key.pem:

public-key.pem

Verify an RSA signature

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

const CALLERS_PUBLIC_KEY = fs.readFileSync("callers-public-key.pem", "utf8");

function isValidRsaSignature(rawBody, signatureB64) {
  if (!signatureB64) return false;
  return crypto.verify(
    "sha256",
    rawBody, // Buffer with the exact bytes received
    CALLERS_PUBLIC_KEY,
    Buffer.from(signatureB64, "base64")
  );
}

const app = express();

// express.raw keeps the body as a Buffer instead of parsing it
app.post("/callers/webhook", express.raw({ type: "*/*" }), (req, res) => {
  if (!isValidRsaSignature(req.body, req.get("X-Signature"))) {
    return res.sendStatus(401);
  }
  const payload = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200);
  // process payload...
});

import base64

from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from flask import Flask, request

with open("callers-public-key.pem", "rb") as f:
    CALLERS_PUBLIC_KEY = serialization.load_pem_public_key(f.read())


def is_valid_rsa_signature(raw_body: bytes, signature_b64: str | None) -> bool:
    if not signature_b64:
        return False
    try:
        CALLERS_PUBLIC_KEY.verify(
            base64.b64decode(signature_b64),
            raw_body,
            padding.PKCS1v15(),
            hashes.SHA256(),
        )
        return True
    except (InvalidSignature, ValueError):
        return False


app = Flask(__name__)


@app.post("/callers/webhook")
def callers_webhook():
    raw = request.get_data()  # exact bytes received
    if not is_valid_rsa_signature(raw, request.headers.get("X-Signature")):
        return "", 401
    payload = request.get_json()
    # process payload...
    return "", 200

The Python example uses the cryptography package (pip install cryptography).

Custom webhooks and HTTP actions: HMAC-SHA256

Custom webhooks created with Create Custom Webhook, and HTTP actions your agents run before, during, or after conversations, are signed with a secret that belongs to your account. Each request includes:

X-Signature: the lowercase hex HMAC-SHA256 of the request body, keyed with your secret.
X-Signature-Type: HMAC.

Get your HMAC secret

Open settings

Open Settings → General in the dashboard.

Reveal the secret

In Webhook Signature, click Show HMAC Secret and copy the value.

Store it securely

Save it as a secret in your server’s environment (for example, CALLERS_HMAC_SECRET). Never put it in client-side code.

Each subaccount has its own secret. Use the secret of the account the agent belongs to.

What is signed

The signature covers the request body after variables are filled in:

Body type	Signed content
JSON or Raw	The body string, exactly as sent.
Form Data	The form fields serialized as compact JSON, in the order you defined them.
None (for example, `GET`)	An empty string.

Verify an HMAC signature

Compute the HMAC of the raw body with your secret and compare it to X-Signature with a constant-time comparison.

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

const SECRET = process.env.CALLERS_HMAC_SECRET;

function isValidHmacSignature(rawBody, signatureHex) {
  if (!signatureHex) return false;
  const expected = crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureHex, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

app.post("/callers/action", express.raw({ type: "*/*" }), (req, res) => {
  const type = req.get("X-Signature-Type");
  const signature = req.get("X-Signature");

  const valid =
    type === "RSA"
      ? isValidRsaSignature(req.body, signature) // see the RSA example above
      : isValidHmacSignature(req.body, signature);

  if (!valid) return res.sendStatus(401);
  res.sendStatus(200);
});

import hashlib
import hmac
import os

from flask import Flask, request

SECRET = os.environ["CALLERS_HMAC_SECRET"].encode()


def is_valid_hmac_signature(raw_body: bytes, signature_hex: str | None) -> bool:
    if not signature_hex:
        return False
    expected = hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_hex)


app = Flask(__name__)


@app.post("/callers/action")
def callers_action():
    raw = request.get_data()
    signature = request.headers.get("X-Signature")

    if request.headers.get("X-Signature-Type") == "RSA":
        valid = is_valid_rsa_signature(raw, signature)  # see the RSA example above
    else:
        valid = is_valid_hmac_signature(raw, signature)

    if not valid:
        return "", 401
    return "", 200

Use RSA instead of HMAC

In the custom webhook or HTTP action editor, turn on Sign with RSA-SHA256. Requests are then signed with the Callers private key, X-Signature-Type is RSA, and you verify them with the public key exactly like simple webhooks. Use this when you don’t want to manage a shared secret.

Text and Email agent webhooks

Signature verification is supported for Voice agent simple webhooks and for custom webhooks and HTTP actions. To authenticate webhooks from Text and Email agents, use a custom webhook (signed with your HMAC secret), or add a secret header in advanced mode and check it on your server.

Unsigned requests

Webhooks in the agent’s Advanced mode (and advanced webhooks created through the API) aren’t signed. Protect them with a secret of your own: add a header such as Authorization: Bearer <random token> in the webhook and reject requests without it. Combine with the Callers IP allowlist.

Best practices

Verify before parsing or processing, and reject failures with 401.
Use constant-time comparison (crypto.timingSafeEqual, hmac.compare_digest) for HMAC.
Keep the HMAC secret out of source control. If it leaks, contact support.
Deduplicate on the call id plus webhookEvent, since retries resend the same signed body.
Use HTTPS only. Callers requires it for simple webhooks.

Troubleshooting

Every signature fails

You’re probably verifying a re-serialized body. In Express, use express.raw() (not express.json()) on the webhook route; in Flask, use request.get_data(); in Django, request.body. Also check you’re using the right scheme: simple webhooks are RSA, custom webhooks default to HMAC.

HMAC fails only for JSON or Form Data custom webhooks

The signature is computed over the compact JSON of the body Callers built (no extra spaces). If a proxy or framework reformatted the body before your code saw it, verify against compact JSON instead: JSON.stringify(JSON.parse(raw)) in Node.js, or json.dumps(json.loads(raw), separators=(",", ":"), ensure_ascii=False) in Python.

HMAC fails but RSA works (or the reverse)

Read X-Signature-Type. HMAC signatures are hex; RSA signatures are base64.

HMAC fails for a subaccount's agent

Use the secret from that subaccount’s settings, not the parent account’s.

The secret isn't shown in Settings

Email to have a webhook secret set up for your account.

Webhooks overview

Delivery, retries, IP allowlist.

Advanced webhooks

Custom requests and signing options.

Actions

HTTP actions that use the same signatures.

Security and privacy

Account-level security settings.

Get started

Guides

Webhooks

Endpoints

Validating webhook signatures

Simple webhooks: RSA-SHA256

Callers public key

Verify an RSA signature

Custom webhooks and HTTP actions: HMAC-SHA256

Get your HMAC secret

What is signed

Verify an HMAC signature

Use RSA instead of HMAC

Text and Email agent webhooks

Unsigned requests

Best practices

Troubleshooting

Webhooks overview

Advanced webhooks

Actions

Security and privacy

​Simple webhooks: RSA-SHA256

​Callers public key

​Verify an RSA signature

​Custom webhooks and HTTP actions: HMAC-SHA256

​Get your HMAC secret

​What is signed

​Verify an HMAC signature

​Use RSA instead of HMAC

​Text and Email agent webhooks

​Unsigned requests

​Best practices

​Troubleshooting

​Related

Webhooks overview

Advanced webhooks

Actions

Security and privacy

Simple webhooks: RSA-SHA256

Callers public key

Verify an RSA signature

Custom webhooks and HTTP actions: HMAC-SHA256

Get your HMAC secret

What is signed

Verify an HMAC signature

Use RSA instead of HMAC

Text and Email agent webhooks

Unsigned requests

Best practices

Troubleshooting

Related