Webhooks Verfügbar (v1)
Mit Webhooks pusht visz.ai Meldungen in deine eigenen Systeme. Wenn in
deinem Arbeitsbereich etwas Nennenswertes passiert, etwa eine Häufung
frustrierter Sitzungen, ein Fehler während eines Kaufvorgangs oder eine
Erwähnung in einem Kommentar, sendet visz.ai einen signierten POST an eine
URL, die du festlegst.
Wo im Dashboard
Einstellungen → Integrationen, Karte Webhook. Im Dialog Webhook einrichten trägst du ein:
- die Ziel-URL: ein öffentlich erreichbarer HTTPS-Endpunkt in deinem System (lokale und private Adressen nimmt visz.ai nicht an),
- ein eigenes Signatur-Secret mit mindestens acht Zeichen, das du auch in deinem System hinterlegst,
- die Ereignisse, die dieser Endpunkt bekommen soll.
Mit Test senden löst du einen echten, signierten Aufruf aus. Einrichten dürfen Inhaber und Admins. Auf derselben Seite verbindest du auch Slack und Shopify und findest Anleitungen für GA4, GTM und WordPress; diese Seite behandelt nur den signierten ausgehenden Webhook.
Zustellmodell
- Methode:
POSTmit JSON-Body an deine Ziel-URL. Weiterleitungen folgt visz.ai nicht; eine Antwort mit3xxgilt als fehlgeschlagen. - Header:
Content-Type: application/json,webhook-id(die Kennung der Meldung) undX-Visz-Signature(HMAC). Prüfe die Signatur, bevor du dem Payload vertraust. - Zeitlimit: Antwortet dein Endpunkt nicht innerhalb von acht Sekunden, gilt der Versuch als fehlgeschlagen.
- Wiederholungen: Fehlgeschlagene Zustellungen (kein
2xxoder Zeitlimit) wiederholt visz.ai mit wachsenden Abständen, insgesamt bis zu acht Versuche über rund zwei Stunden. Scheitern alle, trennt visz.ai die Verbindung; die Karte zeigt sie dann als getrennt, und du verbindest sie neu. - Protokoll: Jeder Versuch steht im Auslieferungsprotokoll der Karte.
Eine Zustellung kannst du dort erneut anstoßen; Endpunkte, die sie schon
mit
2xxbestätigt haben, bekommen sie nicht noch einmal. - Idempotenz: Wegen der Wiederholungen kann dieselbe Meldung mehr als
einmal ankommen.
webhook-idundnotification_idbleiben über alle Versuche gleich; dedupliziere darüber. - Datenminimierung: Payloads enthalten nur pseudonyme Kennungen und einen kurzen Titel, keine Texte aus Kommentaren und keine Besucherdaten.
Die Signatur prüfen
visz.ai signiert Webhooks mit Zeitstempel, damit ein abgefangener Request nicht
später erneut eingespielt werden kann. Der X-Visz-Signature-Header enthält
den Zeitstempel und die Signatur:
X-Visz-Signature: t=1781804392,v1=3f8a…<hex>v1 ist HMAC-SHA256(secret, "{t}.{rawBody}"): Der signierte Payload ist der
Unix-Sekunden-Zeitstempel t, ein Punkt, dann der rohe Request-Body.
Zum Prüfen: t und v1 parsen, den HMAC über `${t}.${rawBody}` neu
berechnen, in konstanter Zeit vergleichen und den Request ablehnen, wenn es
nicht passt. Lehne zusätzlich Zeitstempel ab, die mehr als fünf Minuten von
deiner Uhrzeit abweichen.
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
});Signiere
t.rawBody, nicht den Body allein. Der Zeitstempel ist Teil des HMAC-Inputs und kann daher nicht manipuliert werden. Das erneute Serialisieren des geparsten JSON kann Leerzeichen oder die Reihenfolge der Schlüssel verändern und die Signatur brechen; nutze immer exakt die Bytes, die du empfangen hast.
Payload
Jede Meldung hat dieselbe Form; event sagt dir, was passiert ist.
{
"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"
}| Feld | Beschreibung |
|---|---|
event | Eines der Ereignisse unten. |
notification_id | Kennung der Meldung, über alle Zustellversuche gleich. Nutze sie zum Deduplizieren. |
severity | critical, high, medium, low oder null. |
site_id | Kennung der Website oder null. |
subject | Worum es geht: type und id des Gegenstands. |
title | Kurzer Titel der Meldung in Klartext, auf Deutsch. |
occurred_at | Wann die Meldung entstand (ISO 8601). |
Behandle unbekannte Felder als optional und bestätige schnell mit 2xx; schwere
Arbeit erledigst du asynchron.
Ereignisse
Du wählst, welche Ereignisse ein Endpunkt bekommt. visz.ai verschickt heute diese drei:
frustration_spike
Einmal pro Nacht vergleicht visz.ai den durchschnittlichen Frustrations-Score
jeder Website am Vortag mit dem Mittel der Tage davor. Liegt der Vortag deutlich
darüber, geht diese Meldung raus. subject.type ist site.
blocked_purchase
Ein Besucher ist kurz nach einem Klick auf einen Absende- oder Checkout-Knopf
auf einen JavaScript-Fehler gestoßen. Bekannte, harmlose Meldungen lösen sie
nicht aus, und derselbe Fehler meldet sich nicht bei jedem Vorkommen neu.
subject.type ist error_group.
mention
Jemand hat ein Teammitglied in einem Kommentar zu einer Aufnahme, einer Heatmap
oder einem Highlight erwähnt. subject.type ist recording, heatmap oder
highlight. Der Kommentartext reist nicht mit.
Test
Test senden schickt eine Meldung mit event: "webhook.test", einer
notification_id, einem title und occurred_at, signiert wie jede echte
Zustellung.
Die Auswahl im Dialog kann weitere Einträge zeigen. Verlass dich auf die drei
oben beschriebenen Ereignisse; für error_spike und conversion_drop gibt es
heute keinen Auslöser.
Zuletzt aktualisiert: