Verify signatures
Every request VoisX sends to your endpoint, for alert webhooks and conversation events, is signed with a secret that only you and VoisX know. Check the signature before you act on a request. Anyone can send a POST to your URL; only VoisX can sign it.
Get the signing secret
Each endpoint and each webhook alert rule has its own secret, starting whsec_.
- Conversation events: Settings → Webhooks. The secret is shown once when you add the endpoint. Later, click the key icon on the endpoint to show it again.
- Alert webhooks: Analytics → Alert rules. Click Show secret under the rule.
Showing or rotating a secret needs permission to edit the project.
Store the secret in your secrets manager or an environment variable. Never put it in client-side code or a public repository.
How the signature is made
Each request carries two headers:
| Header | Value |
|---|---|
X-VoisX-Timestamp | When this attempt was sent, in Unix seconds, for example 1761903000. |
X-VoisX-Signature | v1= followed by a hex HMAC-SHA256. |
The signature is computed over the timestamp, a dot and the raw request body:
X-VoisX-Signature = "v1=" + hex(HMAC-SHA256(secret, "<X-VoisX-Timestamp>.<raw body>"))
To verify a request:
- Read
X-VoisX-TimestampandX-VoisX-Signature. Reject the request if either is missing. - Reject the request if the timestamp is more than 5 minutes away from your server's clock. This stops someone replaying a request they captured.
- Compute
v1=+ the hex HMAC-SHA256 of<timestamp>.<raw body>with your secret. - Compare it with
X-VoisX-Signatureusing a constant-time comparison. - Only then parse the JSON body.
Use the body exactly as it arrived, byte for byte. Parsing the JSON and serializing it again changes the bytes, and the signature no longer matches. In most frameworks this means reading the raw body for this route.
Examples
- Node.js
- Python
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.VOISX_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 5 * 60;
// express.raw keeps the body as a Buffer, exactly as it was sent.
app.post("/voisx/webhooks", express.raw({ type: "application/json" }), (req, res) => {
const timestamp = req.get("X-VoisX-Timestamp");
const signature = req.get("X-VoisX-Signature");
if (!timestamp || !signature)
return res.status(400).send("missing signature");
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!(age <= TOLERANCE_SECONDS))
return res.status(400).send("stale timestamp");
const expected = "v1=" + crypto
.createHmac("sha256", SECRET)
.update(`${timestamp}.`)
.update(req.body)
.digest("hex");
const a = Buffer.from(signature);
const b = Buffer.from(expected);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b))
return res.status(401).send("bad signature");
const event = JSON.parse(req.body.toString("utf8"));
const deliveryId = req.get("X-VoisX-Delivery");
// Skip deliveryId if you have already handled it, then queue the work.
res.sendStatus(204);
handleEvent(deliveryId, event);
});
import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["VOISX_WEBHOOK_SECRET"].encode()
TOLERANCE_SECONDS = 5 * 60
@app.post("/voisx/webhooks")
def voisx_webhook():
timestamp = request.headers.get("X-VoisX-Timestamp", "")
signature = request.headers.get("X-VoisX-Signature", "")
body = request.get_data() # the raw bytes, before any JSON parsing
try:
age = abs(time.time() - int(timestamp))
except ValueError:
abort(400)
if age > TOLERANCE_SECONDS:
abort(400)
expected = "v1=" + hmac.new(SECRET, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
abort(401)
event = request.get_json()
delivery_id = request.headers["X-VoisX-Delivery"]
# Skip delivery_id if you have already handled it, then queue the work.
handle_event(delivery_id, event)
return "", 204
Retries and the timestamp
A retry is signed again when it is sent, with a new X-VoisX-Timestamp. So a retry an hour later still passes a 5-minute check. Its X-VoisX-Delivery header and body stay the same, which is how you spot a duplicate.
Rotate a secret
Rotate the secret if it may have leaked, or as routine hygiene:
- Click Rotate secret (conversation events) or Rotate (alert rules) and confirm.
- Copy the new secret into your receiver's configuration straight away.
The new secret applies from the next request, including retries of earlier events, and the old one stops verifying at once. A request your endpoint rejects with 401 isn't retried. If events may arrive while you update the receiver, answer 503 instead of 401 for a failed signature check for a few minutes, so VoisX retries those requests with the new secret.
Test your receiver
In Settings → Webhooks, click Send test event on an endpoint. VoisX sends one signed webhook.test event and shows the status your endpoint answered. A 2xx means your endpoint accepted it; a 401 usually means the secret or the raw-body handling is wrong.
{
"id": "evt_3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e",
"type": "webhook.test",
"created_at": "2026-10-31T09:00:00.000000+00:00",
"project_id": 345,
"data": { "endpoint_id": 7 }
}