Skip to Content

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:

  1. the Target URL: a publicly reachable HTTPS endpoint in your system (visz.ai does not accept local or private addresses),
  2. your own Signature secret of at least eight characters, which you also store in your system,
  3. 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: POST with a JSON body to your target URL. visz.ai does not follow redirects; a 3xx response counts as failed.
  • Headers: Content-Type: application/json, webhook-id (the notice identifier) and X-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 2xx or 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 2xx do not get it a second time.
  • Idempotency: because of retries, the same notice may arrive more than once. webhook-id and notification_id stay 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" }
FieldDescription
eventOne of the events below.
notification_idIdentifier of the notice, the same across all delivery attempts. Use it to deduplicate.
severitycritical, high, medium, low, or null.
site_idIdentifier of the website, or null.
subjectWhat it is about: type and id of the subject.
titleShort plain-text title of the notice, in German.
occurred_atWhen 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: