Webhooks

Erhalten Sie eine signierte HTTPS-Anfrage an Ihrer eigenen URL, wenn auf Ihrer Website etwas passiert.

Endpunkt einrichten

Öffnen Sie die Website-Einstellungen, Tab Daten, Bereich Webhooks. Tragen Sie die URL ein, wählen Sie die Auslöser und kopieren Sie das Signatur-Geheimnis. Es wird nur einmal angezeigt; Sie können es später erneuern. Webhooks gibt es ab dem Starter-Tarif. Jede Website kann bis zu 10 Endpunkte haben, und ein Endpunkt gehört zu genau einer Website.

Auslöser

  • event.received: ein von Ihnen benanntes eigenes Event (bis zu 20 Namen pro Endpunkt). Eine Anfrage pro Event.
  • goal.converted: ein Ziel wurde erreicht, einmal pro Sitzung und Ziel. Enthält die Traffic-Quelle des Besuchs. Wählen Sie alle Ziele oder bestimmte.
  • alert.triggered: einer Ihrer Traffic-Alarme hat ausgelöst.
  • uptime.down und uptime.up: Ihre Website antwortet nicht mehr oder wieder.

Events und Ziele werden etwa einmal pro Minute erfasst. Rechnen Sie mit 30 bis 90 Sekunden Verzögerung.

Inhalt

JSON-Endpunkte erhalten einen Body im Standard-Webhooks-Format. Das Feld text ist eine einzeilige Zusammenfassung auf Englisch.

{
  "id": "whd_1234",
  "type": "goal.converted",
  "created_at": "2026-10-27T10:15:00Z",
  "site": { "id": "5b1f0c2e-...", "domain": "example.com" },
  "data": {
    "goal": { "id": "...", "name": "Signup", "type": "pageview", "target": "/thanks" },
    "pathname": "/thanks",
    "occurred_at": "2026-10-27T10:14:41.000Z",
    "source": {
      "channel": "Organic Search",
      "referrer_domain": "google.com",
      "utm_source": null,
      "utm_medium": null,
      "utm_campaign": null
    }
  },
  "text": "Goal \"Signup\" converted on example.com (from Organic Search)."
}

Der Inhalt enthält nie Besucher- oder Sitzungs-IDs, IP-Adressen oder Städte. Event-Eigenschaften sind die, die Sie selbst gesendet haben. Der Inhalt ist auf 64 KB begrenzt; passen die Eigenschaften nicht hinein, werden sie weggelassen und truncated ist true.

Slack und Discord

Wählen Sie das Format Slack oder Discord, um die Textzusammenfassung statt des JSON-Umschlags an eine Incoming-Webhook-URL zu senden.

Header und Signatur

  • webhook-id: die Zustell-ID. Sie bleibt bei Wiederholungen gleich, damit Sie Duplikate ignorieren können.
  • webhook-timestamp: Unix-Sekunden dieses Versuchs.
  • webhook-signature: v1, gefolgt vom Base64-HMAC-SHA256 über id.timestamp.body, mit Ihrem Geheimnis als Schlüssel (Base64-dekodiert, ohne das Präfix whsec_).

Anfrage prüfen

Jede Standard-Webhooks-Bibliothek funktioniert. In Node.js ohne Bibliothek:

import { createHmac, timingSafeEqual } from "node:crypto";

// secret: the whsec_... value shown once when you created the endpoint
// rawBody: the request body exactly as received (a string, not parsed JSON)
export function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64");

  return headers["webhook-signature"].split(" ").some((part) => {
    const [version, sig] = part.split(",");
    if (version !== "v1") return false;
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

Wiederholungen und Deaktivierung

Antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status. Alles andere gilt als Fehlschlag und wird nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden und 8 Stunden wiederholt, insgesamt etwa 11 Stunden. Weiterleitungen werden nicht verfolgt.

Eine 410-Antwort deaktiviert den Endpunkt sofort. Nach 25 Fehlschlägen in Folge ohne Erfolg in 24 Stunden wird er deaktiviert und der Website-Inhaber erhält eine E-Mail. Schalten Sie ihn in den Einstellungen wieder ein, sobald die URL funktioniert. Unter Zustellungen eines Endpunkts sehen Sie die letzten 50 Versuche und können fehlgeschlagene wiederholen.

Grenzen

  • Eigene Events: höchstens 500 Zustellungen pro Stunde und Endpunkt. Events darüber werden in den Einstellungen gezählt, aber nicht gesendet.
  • Nur öffentliche https-URLs. Adressen in privaten Netzwerken werden blockiert.
  • Events einer Subdomain-Website gehen an die Endpunkte dieser Subdomain-Website.

Selbst hosten

Setzen Sie WEBHOOKS_ALLOW_PRIVATE=1, um Endpunkte im eigenen Netzwerk und einfaches http zu erlauben. Siehe die Self-Hosting-Anleitung.