Verifying Pure CallerID Webhooks

Every webhook Pure CallerID sends is signed. Checking the signature tells you two things:

• The request really came from Pure CallerID.
• The payload was not changed after we sent it.

Each webhook also has a unique message ID and the time we first tried to send it. Use these to ignore duplicates and to see how late a retry is.

We use the open Standard Webhooks format, so you can use one of its free libraries or write the check yourself in a few lines.

Find your signing secret

Each workspace has one signing secret, shared by every webhook in that workspace.

1. Open Workspace settings for the workspace.
2. Find the Webhook signing secret section.
3. Click Reveal, then click the copy icon.

The secret looks like whsec_ followed by a long random string. Store it as securely as you would a password, for example in an environment variable or a secrets manager. Never put it in client-side code or source control.

Only Owners and Admins can view or rotate the secret.

Webhook headers

These headers come with every webhook:

Webhooks set up under Workspace settings → Webhooks also include:

If you set a Basic, Bearer or custom header on the webhook, we send that as well.

Callback URLs on campaign lists: if you set a webhookUrl on a campaign list through the API, that callback is signed the same way and includes webhook-id, webhook-timestamp and webhook-signature. It does not include the X-Event-* or X-Retry-* headers, and it is not retried.

How the signature is built

1. Build the signed content by joining the message ID, the timestamp and the raw request body with periods:

   {webhook-id}.{webhook-timestamp}.{raw body}

    
2. Take your signing secret, remove the whsec_ prefix and base64-decode the rest. The result is the key.
3. Compute an HMAC-SHA256 of the signed content with that key, then base64-encode the result.
4. Compare your value with the part of webhook-signature after v1,.

The webhook-signature header can hold several signatures separated by spaces, for example v1,abc= v1,def=. The request is valid if any of them matches. Today we send one, but build your check to accept a list so it keeps working if that changes.

Important

• Use the raw body, byte for byte. Read the request body as raw bytes or a string before any JSON parsing. If you parse the JSON and convert it back to text, spacing and key order can change and the signature will not match.
• Use a constant-time comparison, such as hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js, instead of ==.
• Check the timestamp. Reject a request if webhook-timestamp is more than 5 minutes from your server's current time. This blocks someone from replaying an old captured request. Each retry gets a new webhook-timestamp and signature, so retries still pass this check. Use X-Retry-Original-Timestamp to see when the message was first sent.
• Ignore duplicates. Keep the webhook-id values you have already processed. If one comes again, return 200 without processing it a second time.

Code examples

Using a Standard Webhooks library (recommended)

Official libraries exist for Node.js, Python, Go, Java, PHP, Ruby, C#, Rust and more. See github.com/standard-webhooks/standard-webhooks. They check the signature and the timestamp for you.

Node.js (npm install standardwebhooks)

import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.PCID_WEBHOOK_SECRET); // "whsec_..."

// express.raw keeps the body as the exact bytes we sent
app.post("/pcid-webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const payload = wh.verify(req.body, req.headers);
    // payload is the parsed JSON; req.headers["webhook-id"] is the message ID
    res.sendStatus(200);
  } catch (err) {
    res.sendStatus(401);
  }
});

Python (pip install standardwebhooks)

import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook

app = Flask(__name__)
wh = Webhook(os.environ["PCID_WEBHOOK_SECRET"])  # "whsec_..."

@app.post("/pcid-webhook")
def pcid_webhook():
    try:
        payload = wh.verify(request.get_data(), dict(request.headers))
    except Exception:
        return "", 401
    return "", 200

Checking it yourself (no library)

Node.js

const crypto = require("crypto");

function verifyPcidWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

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

  return signatures.split(" ").some((s) => {
    const [version, value] = s.split(",");
    if (version !== "v1" || !value) return false;
    const received = Buffer.from(value, "base64");
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

Python

import base64, hashlib, hmac, time

def verify_pcid_webhook(secret: str, headers, raw_body: bytes) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not (msg_id and timestamp and signatures):
        return False

    if abs(time.time() - int(timestamp)) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    return any(
        version == "v1" and hmac.compare_digest(value, expected)
        for version, _, value in (s.partition(",") for s in signatures.split(" "))
    )        for version, _, value in (s.partition(",") for s in signatures.split(" "))    )

Test your code

Run your check on these values. Turn off the timestamp check while you do, because this timestamp is from 2021. Your code should report valid.

Change any single character of the body, ID or timestamp, and your code should report invalid.

Retries

If Retry on failure is turned on for a webhook and your endpoint does not respond with a success code, we try again. Success means a 2xx status or any code you added under positive response codes. There are up to 5 attempts in total:

The last retry is about 23 minutes after the first attempt, or up to about 25 minutes if your endpoint is timing out.

Every retry has the same webhook-id, X-Retry-Original-Timestamp and body. It has a new webhook-timestamp and webhook-signature.

Respond within 20 seconds; after that, the attempt counts as failed. If processing takes longer, return 200 right away and finish the work in the background.

If a webhook keeps failing for more than 60 minutes, we disable it automatically and notify your workspace. You can turn it back on from Workspace settings → Webhooks.

Rotating your signing secret

If you think your secret has been exposed, rotate it:

1. Open Workspace settings → Webhook signing secret.
2. Click Rotate and type ROTATE to confirm.
3. Copy the new secret and update every endpoint that checks it.

Rotating takes effect immediately. All future webhooks are signed with the new secret, including retries of messages already in progress. The old secret stops working right away. Until your endpoints are updated, they will reject our webhooks. Plan a rotation for a time when you can update your systems quickly.

Troubleshooting

Signature never matches

• Make sure you are using the raw body and not JSON that was parsed and converted back to text. Many frameworks parse JSON automatically, so turn that off for the webhook route.
• Make sure you are using the secret for the same workspace that the webhook belongs to.
• Make sure you remove whsec_ and base64-decode the rest. Using the secret text directly as the key gives a different result.
• If you rotated the secret recently, check that your endpoint has the new one.

Timestamp check fails

• Make sure your server clock is correct. Use NTP.
• webhook-timestamp is in seconds, not milliseconds.

I received the same event twice

• That is expected after a timeout or a non-success response. Use webhook-id to process each message only once.