Validating Webhook Signatures

Callers signs the requests it sends to your endpoints - webhooks after a conversation and custom actions during it. Check the signature to make sure a request really comes from Callers and wasn’t changed on the way.

How Requests Are Signed

Every signed request carries two headers:

X-Signature: The signature of the request body.
X-Signature-Type: How the request was signed - HMAC or RSA.

Type	When it’s used	Verify with	Signature format
`HMAC` (default)	Unless RSA is turned on	Your account’s HMAC secret	HMAC-SHA256, hex
`RSA`	When Sign with RSA-SHA256 is turned on in the request’s settings	The Callers public key below	RSA-SHA256, base64

The Sign with RSA-SHA256 toggle, turned off, with the note that HMAC-SHA256 is used when it's disabled — The RSA option in a webhook's settings

The signature is calculated over the request body exactly as Callers sends it - for a JSON body, the compact JSON text. Verify it against the raw body of the request, before your framework parses it.

Read X-Signature-Type on every request and pick the matching check, so your endpoint works whichever way a request is signed.

Find Your HMAC Secret

Click your name at the bottom of the sidebar, choose Settings and stay on the General tab. Under Webhook Signature, click Show HMAC Secret and copy the key. See Account Settings.

Each account - including each subaccount - has its own secret. Use the secret of the account the agent belongs to.
Use the secret as is, as a text string. Don’t decode it.
Keep it private, like a password. If you think it has leaked, contact support.

Verify an HMAC Signature

Take the raw request body and the X-Signature header.
Calculate the HMAC-SHA256 of the body with your secret, as a hex string.
Compare the result with X-Signature using a constant-time comparison. If they don’t match, reject the request.

JavaScript (Node.js with Express)

const crypto = require('crypto');
const express = require('express');

const app = express();
const HMAC_SECRET = process.env.CALLERS_HMAC_SECRET;

// Keep the raw body - the signature is calculated over it
app.post('/callers-webhook', express.raw({ type: '*/*' }), (req, res) => {
  const signature = req.get('X-Signature') || '';

  if (req.get('X-Signature-Type') !== 'HMAC') {
    return res.sendStatus(400); // see "Verify an RSA Signature" below
  }

  const expected = crypto
    .createHmac('sha256', HMAC_SECRET)
    .update(req.body)
    .digest('hex');

  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

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

  const payload = JSON.parse(req.body.toString('utf8'));
  // ...process the payload
  res.sendStatus(200);
});

Python

import hashlib
import hmac


def is_valid_hmac(raw_body: bytes, signature: str, secret: str) -> bool:
    """Check the X-Signature header of a Callers request signed with HMAC."""
    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Verify an RSA Signature

Requests with X-Signature-Type: RSA are signed with the Callers private key. Verify them with this public key:

public-key.pem

JavaScript (Node.js)

const crypto = require('crypto');
const fs = require('fs');

const publicKey = fs.readFileSync('path/to/public-key.pem', 'utf8');

// rawBody: the request body as received (Buffer or string)
// signature: the X-Signature header (base64)
function isValidRsa(rawBody, signature) {
  const verify = crypto.createVerify('RSA-SHA256');
  verify.update(rawBody);
  verify.end();
  return verify.verify(publicKey, signature, 'base64');
}

Python

This example uses the pycryptodome package (pip install pycryptodome).

import base64

from Crypto.Hash import SHA256
from Crypto.PublicKey import RSA
from Crypto.Signature import pkcs1_15


def is_valid_rsa(raw_body: bytes, signature_b64: str, public_key_path: str) -> bool:
    """Check the X-Signature header of a Callers request signed with RSA."""
    with open(public_key_path, "rb") as f:
        public_key = RSA.import_key(f.read())
    try:
        pkcs1_15.new(public_key).verify(SHA256.new(raw_body), base64.b64decode(signature_b64))
        return True
    except (ValueError, TypeError):
        return False

Get Started

Build Your Agent

Using Callers

Integrations

Agencies

Webhook

Resources

Legal

Validating Webhook Signatures

How Requests Are Signed

Find Your HMAC Secret

Verify an HMAC Signature

JavaScript (Node.js with Express)

Python

Verify an RSA Signature

JavaScript (Node.js)

Python

​How Requests Are Signed

​Find Your HMAC Secret

​Verify an HMAC Signature

​JavaScript (Node.js with Express)

​Python

​Verify an RSA Signature

​JavaScript (Node.js)

​Python

How Requests Are Signed

Find Your HMAC Secret

Verify an HMAC Signature

JavaScript (Node.js with Express)

Python

Verify an RSA Signature

JavaScript (Node.js)

Python