Webhooks Available (v1)
Webhooks let visz.ai push notices to your own systems. When something
noteworthy happens in your workspace, such as a surge of frustrated sessions,
an error during a purchase, or a mention in a comment, visz.ai sends a signed
POST to a URL you choose.
Where in the dashboard
Settings → Integrations, card Webhook. In the Set up webhook dialog you enter:
- the Target URL: a publicly reachable HTTPS endpoint in your system (visz.ai does not accept local or private addresses),
- your own Signature secret of at least eight characters, which you also store in your system,
- the events this endpoint should receive.
Send test fires a real, signed call. Owners and admins can set this up. On the same page you also connect Slack and Shopify and find guides for GA4, GTM, and WordPress; this page covers the signed outbound webhook only.
Delivery model
- Method:
POSTwith a JSON body to your target URL. visz.ai does not follow redirects; a3xxresponse counts as failed. - Headers:
Content-Type: application/json,webhook-id(the notice identifier) andX-Visz-Signature(HMAC). Verify the signature before trusting the payload. - Timeout: if your endpoint does not answer within eight seconds, the attempt counts as failed.
- Retries: failed deliveries (no
2xxor timeout) are retried at growing intervals, up to eight attempts in total over about two hours. If all of them fail, visz.ai disconnects the integration; the card then shows it as disconnected, and you connect it again. - Log: every attempt appears in the card’s delivery log. You can trigger
a delivery again from there; endpoints that already acknowledged it with
2xxdo not get it a second time. - Idempotency: because of retries, the same notice may arrive more than
once.
webhook-idandnotification_idstay the same across all attempts; deduplicate on them. - Data minimization: payloads carry only pseudonymous identifiers and a short title, no comment text and no visitor data.
Verifying the signature
visz.ai signs webhooks with a timestamp so that an intercepted request cannot
be replayed later. The X-Visz-Signature header carries the timestamp and the
signature:
X-Visz-Signature: t=1781804392,v1=3f8a…<hex>v1 is HMAC-SHA256(secret, "{t}.{rawBody}"): the signed payload is the
unix-second timestamp t, a literal dot, then the raw request body. To
verify: parse t and v1, recompute the HMAC over `${t}.${rawBody}`,
compare in constant time, and reject the request if it does not match. Also
reject timestamps that differ from your clock by more than five minutes.
import { createHmac, timingSafeEqual } from "node:crypto";
// Express example: make sure you have the RAW body, not the parsed JSON.
function verifyViszWebhook(rawBody, header, signingSecret, toleranceSec = 300) {
// header looks like: t=1781804392,v1=<hex>
const parts = Object.fromEntries(
String(header ?? "")
.split(",")
.map((p) => p.split("=").map((s) => s.trim()))
);
const t = parts.t;
const v1 = parts.v1;
if (!/^\d+$/.test(t ?? "") || !v1) return false;
// Replay guard: reject signatures outside the tolerance window.
if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSec) return false;
const expected = createHmac("sha256", signingSecret)
.update(`${t}.${rawBody}`, "utf8") // signed payload = "{timestamp}.{rawBody}"
.digest("hex");
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(v1, "utf8");
return a.length === b.length && timingSafeEqual(a, b);
}
app.post("/visz-webhook", express.raw({ type: "application/json" }), (req, res) => {
const ok = verifyViszWebhook(
req.body.toString("utf8"), // raw body as received
req.header("X-Visz-Signature"),
process.env.VISZ_WEBHOOK_SECRET
);
if (!ok) return res.status(401).end();
const payload = JSON.parse(req.body.toString("utf8"));
// handle payload.event, dedupe on payload.notification_id
res.status(200).end(); // ack quickly; do the work async
});Sign
t.rawBody, not the body alone. The timestamp is part of the HMAC input, so it cannot be tampered with. Re-serializing the parsed JSON can change whitespace or key order and break the signature; always use the exact bytes you received.
Payload
Every notice has the same shape; event tells you what happened.
{
"event": "frustration_spike",
"notification_id": "0192f3a4-b5c6-7d8e-9f01-23456789abcd",
"severity": "high",
"site_id": "0192f3a4-0000-7000-8000-000000000001",
"subject": { "type": "site", "id": "0192f3a4-0000-7000-8000-000000000001" },
"title": "Auffällig viele frustrierte Sitzungen gestern",
"occurred_at": "2026-09-24T06:30:00.000Z"
}| Field | Description |
|---|---|
event | One of the events below. |
notification_id | Identifier of the notice, the same across all delivery attempts. Use it to deduplicate. |
severity | critical, high, medium, low, or null. |
site_id | Identifier of the website, or null. |
subject | What it is about: type and id of the subject. |
title | Short plain-text title of the notice, in German. |
occurred_at | When the notice was created (ISO 8601). |
Treat unknown fields as optional and acknowledge with a 2xx quickly; do heavy
work asynchronously.
Events
You choose which events an endpoint receives. Today visz.ai sends these three:
frustration_spike
Once a night, visz.ai compares each website’s average frustration score of the
previous day with the mean of the days before. If the previous day is clearly
higher, this notice goes out. subject.type is site.
blocked_purchase
A visitor hit a JavaScript error shortly after clicking a submit or checkout
button. Known, harmless messages do not trigger it, and the same error does not
report again on every occurrence. subject.type is error_group.
mention
Someone mentioned a teammate in a comment on a recording, a heatmap, or a
highlight. subject.type is recording, heatmap, or highlight. The
comment text does not travel with it.
Test
Send test sends a notice with event: "webhook.test", a
notification_id, a title, and occurred_at, signed like every real
delivery.
The selection in the dialog may show further entries. Rely on the three events
described above; error_spike and conversion_drop have no trigger today.
Last updated: