Skip to Content
API-ReferenzWebhooks

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:

  1. die Ziel-URL: ein öffentlich erreichbarer HTTPS-Endpunkt in deinem System (lokale und private Adressen nimmt visz.ai nicht an),
  2. ein eigenes Signatur-Secret mit mindestens acht Zeichen, das du auch in deinem System hinterlegst,
  3. 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: POST mit JSON-Body an deine Ziel-URL. Weiterleitungen folgt visz.ai nicht; eine Antwort mit 3xx gilt als fehlgeschlagen.
  • Header: Content-Type: application/json, webhook-id (die Kennung der Meldung) und X-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 2xx oder 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 2xx bestätigt haben, bekommen sie nicht noch einmal.
  • Idempotenz: Wegen der Wiederholungen kann dieselbe Meldung mehr als einmal ankommen. webhook-id und notification_id bleiben ü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" }
FeldBeschreibung
eventEines der Ereignisse unten.
notification_idKennung der Meldung, über alle Zustellversuche gleich. Nutze sie zum Deduplizieren.
severitycritical, high, medium, low oder null.
site_idKennung der Website oder null.
subjectWorum es geht: type und id des Gegenstands.
titleKurzer Titel der Meldung in Klartext, auf Deutsch.
occurred_atWann 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: