Verify webhook requests#

Every webhook request is signed with the secret of your webhook. Verify the signature before you process an event, so that your server accepts only requests that come from phone.systems™ and that were not changed on the way.

Before you begin#

A webhook must be added in Settings > Webhooks. See Set up and manage a webhook.
The secret of the webhook must be stored on your server. See View the webhook status and secret.
Your server must read the raw request body. Parsing and re-serializing the JSON changes the bytes and breaks the signature.

How requests are signed#

Each request has an X-PS-Signature header in this format:

X-PS-Signature: t=1790847297,v1=f7b25eab66fb2113b8ec6f313a2ee18d8a7c4fa47cf9e9dc0993f5758b17e906

Part	Description
`t`	The time the delivery attempt was signed, in Unix seconds.
`v1`	The HMAC-SHA256 of the signed payload, as a lowercase hexadecimal string. The key is the webhook secret.

The signed payload is the value of t, a period (.), and the raw request body, exactly as received:

<t>.<raw request body>

Each delivery attempt is signed again, so a retried request has a new t and a new v1.

Step 1: Verify the signature#

For every request:

Read the X-PS-Signature header. Split it on ,, then split each part on the first =. Take t and v1. Reject the request if the header is missing, t is not a number, or v1 is not 64 lowercase hexadecimal characters.
Reject the request if t is more than 5 minutes before or after the current time. This protects against replayed requests. Keep the clock of your server synchronized with NTP.
Build the signed payload <t>.<raw request body> from the raw body bytes.
Compute the HMAC-SHA256 of the signed payload with the webhook secret as the key, and encode it as lowercase hexadecimal. Use the secret as text, exactly as shown on the Webhooks page. Do not base64-decode it.
Compare the result with v1 using a constant-time comparison. If they do not match, reject the request.

Use one of the following functions, or implement the same steps in your language. Both were tested against real phone.systems™ requests.

Python

Requires Python 3.10 or later and no extra packages.

import hashlib
import hmac
import re
import time

TOLERANCE_SECONDS = 300
TIMESTAMP = re.compile(r"[0-9]{1,12}")
SIGNATURE = re.compile(r"[0-9a-f]{64}")


def verify_signature(secret: str, raw_body: bytes, signature_header: str,
                     now: float | None = None) -> bool:
    """Return True if the X-PS-Signature header matches the raw request body."""
    fields = [part.strip().partition("=") for part in signature_header.split(",")]
    timestamp = next((value for key, _, value in fields if key == "t"), "")
    signatures = [value for key, _, value in fields
                  if key == "v1" and SIGNATURE.fullmatch(value)]
    if not TIMESTAMP.fullmatch(timestamp) or not signatures:
        return False

    if now is None:
        now = time.time()
    if abs(now - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed_payload = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, signature) for signature in signatures)

Node.js

Uses the built-in crypto module.

const crypto = require("crypto");

const TOLERANCE_SECONDS = 300;
const TIMESTAMP = /^[0-9]{1,12}$/;
const SIGNATURE = /^[0-9a-f]{64}$/;

function verifySignature(secret, rawBody, signatureHeader, now = Date.now() / 1000) {
  const fields = String(signatureHeader).split(",").map((part) => {
    const index = part.indexOf("=");
    return index === -1 ? [part.trim(), ""] : [part.slice(0, index).trim(), part.slice(index + 1)];
  });
  const timestamp = fields.find(([key]) => key === "t")?.[1] ?? "";
  const signatures = fields
    .filter(([key, value]) => key === "v1" && SIGNATURE.test(value))
    .map(([, value]) => value);
  if (!TIMESTAMP.test(timestamp) || signatures.length === 0) return false;
  if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");

  return signatures.some((signature) =>
    crypto.timingSafeEqual(Buffer.from(signature, "ascii"), Buffer.from(expected, "ascii"))
  );
}

module.exports = { verifySignature };

Test your implementation#

Check your code with these example values before you connect it to your webhook. With them, your function must return a valid result. Changing any character of the body, the timestamp, or the secret must make it fail.

Input	Example value
Secret	`example_secret_do_not_use_7f3a9c1e5b2d8f4a6c0e9b1d3f5a7c9e1b`
`X-PS-Signature`	`t=1790847297,v1=f7b25eab66fb2113b8ec6f313a2ee18d8a7c4fa47cf9e9dc0993f5758b17e906`
Raw body	The JSON below, as one line with no spaces between elements.

{"id":"d75df7ee-5c1f-7a9f-b213-5cb13ccc38b7","type":"call.started","ts":"2026-10-01T09:34:57.221Z","global_tag":"faf24793-bbd2-4ef0-a94c-6dcc2215207b","data":{"catch_up":false,"reason":null,"time_start":"2026-10-01T09:34:57Z","time_connect":null,"time_end":null,"src_type":"user","src_number":"15551230001","src_name":"Alex Smith","dst_type":null,"dst_number":"15551230002","end_reason":null,"disconnect_code":null,"disconnect_reason":null}}

The example timestamp is in the past, so pass it as the current time when you test, for example now=1790847298 in Python or 1790847298 as the fourth argument in Node.js. Otherwise the 5-minute check rejects it.

Step 2: Handle the request#

After the signature is valid:

Parse the body as JSON.
Check the event id. If you already processed an event with the same id, respond with 200 and skip it. Retries and replays reuse the same id. See Duplicate events.
Store the event and respond with a 2xx status code within 10 seconds. Process the event after you respond, for example from a queue, so that slow processing does not cause timeouts and retries.

If the signature is invalid, respond with 401 and do not process the event.

The following examples read the raw body and call the verification function from step 1. The secret is read from the PS_WEBHOOK_SECRET environment variable.

Python (Flask)

import json
import os

from flask import Flask, request

from verify import verify_signature  # the function from step 1

app = Flask(__name__)
SECRET = os.environ["PS_WEBHOOK_SECRET"]


@app.post("/webhook")
def webhook():
    raw_body = request.get_data()  # raw bytes, before JSON parsing
    signature = request.headers.get("X-PS-Signature", "")
    if not verify_signature(SECRET, raw_body, signature):
        return "", 401

    event = json.loads(raw_body)
    # Skip the event if event["id"] was already processed.
    # Otherwise store it and process it asynchronously.
    return "", 200

Node.js (Express)

const express = require("express");
const { verifySignature } = require("./verify"); // the function from step 1

const app = express();
const SECRET = process.env.PS_WEBHOOK_SECRET;

// express.raw keeps the body as a Buffer, so the signature can be checked.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.get("X-PS-Signature") || "";
  if (!verifySignature(SECRET, req.body, signature)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body);
  // Skip the event if event.id was already processed.
  // Otherwise store it and process it asynchronously.
  res.sendStatus(200);
});

app.listen(3000);

When the signature does not match#

Important

Do not log the secret or the X-PS-Signature header together with the raw body.
Use HTTPS on your server, and turn on Skip certificate verification only for a server with a self-signed, expired, or mismatched certificate.
Payloads can contain personal data, such as phone numbers, caller names, transcripts, and summaries. Store and retain them according to your privacy and data protection requirements.