Webhooks

Mit einem Webhook schickt SitePrio Warnungen direkt an Ihr eigenes System, zum Beispiel an ein Ticketsystem oder eine Automatisierung. Hier steht, was ankommt, wie Sie die Signatur prüfen und worauf Sie sich verlassen können.

AnfragePOST, JSONnur HTTPS, Port 443
Antwort2xx in 15 sInhalt wird nicht ausgewertet
Versuchebis 5mit derselben webhook-id
SignaturHMAC-SHA256nach Standard Webhooks

Einrichten

Webhooks gibt es in den Tarifen Business und Agentur. In SitePrio tragen Sie unter „Benachrichtigungen“ → „Webhook“ die HTTPS-Adresse Ihres Systems ein: Port 443, ohne IP-Adresse und ohne Zugangsdaten in der Adresse. Den Schlüssel für die Signatur (whsec_…) zeigen wir nur einmal: Bewahren Sie ihn sicher auf.

Welche Warnungen kommen, legen Sie dort unter „Wann wir Sie benachrichtigen“ fest. Mit „Testnachricht senden“ prüfen Sie die Verbindung.

Zu den Benachrichtigungen

Was ankommt

Zu jeder Nachricht schickt SitePrio eine POST-Anfrage an Ihre Adresse: im Body ein JSON-Objekt in UTF-8, dazu diese Kopfzeilen.

KopfzeileWertBedeutung
content-type application/json Der Body ist JSON in UTF-8.
webhook-id <UUID> Kennung der Nachricht. Bei jedem Versuch derselben Nachricht gleich: Daran erkennen Sie Wiederholungen.
webhook-timestamp <Unix> Zeitpunkt dieses Versuchs in ganzen Sekunden (Unix-Zeit, UTC).
webhook-signature v1,<base64> Signatur der Nachricht. Heute kommt eine v1-Signatur; nach dem Standard können mehrere durch Leerzeichen getrennt kommen: Prüfen Sie jede.

Signatur prüfen

Die Signatur ist ein HMAC-SHA256 der Zeichenkette <webhook-id>.<webhook-timestamp>.<Body> mit Ihrem Schlüssel (der Base64-Teil nach whsec_). Die Bibliotheken von Standard Webhooks (für JavaScript, Python, Go, Java, PHP, Ruby und andere) nehmen den Schlüssel whsec_… so, wie er ist.

Standard Webhooks: Anleitung und Bibliotheken

Von Hand, hier in Node.js: Prüfen Sie den rohen Body, so wie er ankommt, noch bevor Sie das JSON lesen. Das Fenster von 5 Minuten schützt davor, dass jemand eine abgefangene Anfrage später noch einmal schickt.

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

function verify(secret, headers, rawBody) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  if (!id || !timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();
  return String(headers['webhook-signature'] ?? '')
    .split(' ')
    .some((signature) => {
      const [version, value] = signature.split(',');
      const given = Buffer.from(value ?? '', 'base64');
      return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
    });
}

Zum Testen: Mit diesen Werten und dem Body aus Beispiel 1 in kompakter Form (JSON.stringify ohne Leerzeichen und Zeilenumbrüche, so wird er gesendet) muss die Signatur übereinstimmen. Schalten Sie für diese Testwerte das Fenster von 5 Minuten ab: Diese Werte sind älter, und verify() lehnt sie sonst ab.

secret: whsec_AwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMD
webhook-id: 019a3f5c-8e40-7b2d-9c41-6f0e2d7a1b35
webhook-timestamp: 1790856300
webhook-signature: v1,MapunbrFrWmC9LJUvh7evkl3aKWb/DavYD5+gwzzFHA=

Aufbau der Nachricht

Jede Nachricht ist ein JSON-Objekt mit diesen Feldern, in dieser Reihenfolge:

FeldInhalt
type Art der Nachricht, zum Beispiel incident_down (Tabelle unten).
category alert – sofortige Warnung, digest – Zusammenfassung der Stunde, transactional – Testnachricht.
timestamp Zeitpunkt dieses Versuchs (ISO 8601, UTC, mit Millisekunden), derselbe wie in webhook-timestamp. Wann das Ereignis war, steht in data.
text Der fertige Text, wie in Telegram und Slack: Betreff, Leerzeile, Nachricht. Bis zu 3500 Zeichen, in der Sprache des Kontos (de, en oder uk).
data Die Angaben zur Nachricht, je nach Art (unten). Einmal-Links enthält es nie.

Arten von Nachrichten

Per Webhook kommen nur diese Nachrichten. Wochenbericht und Monatsbericht gibt es nur per E-Mail, ebenso alles rund um Ihr Konto, etwa Rechnungen.

Art Wann Wichtige Felder
incident_down Die Website ist nicht erreichbar. siteUrl, startedAt, cause, confidence, timezone
incident_reminder Die Website ist immer noch nicht erreichbar (Erinnerung, wenn eingestellt). siteUrl, startedAt, cause, at
incident_recovered Die Website ist wieder erreichbar (wenn wir den Ausfall gemeldet haben). siteUrl, startedAt, resolvedAt, cause
site_unstable Drei Ausfälle innerhalb von 2 Stunden: eine Nachricht statt vieler. siteUrl, count
site_slow Die Website ist auffällig langsam (wenn eingeschaltet), höchstens einmal am Tag. pageUrl, seconds, thresholdSeconds
keyword_missing Ein überwachter Inhalt fehlt, oder ein unerwünschter ist aufgetaucht. pageUrl, keyword, mode, what
ssl_expiring Das SSL-Zertifikat läuft bald ab oder ist abgelaufen. host, daysLeft, validTo
ssl_invalid Das Zertifikat passt nicht zur Adresse oder ist nicht vertrauenswürdig. host, problem
domain_expiring Die Registrierung der Domain läuft bald ab oder ist abgelaufen. domain, daysLeft, expiresAt
dns_ns_changed Die Nameserver der Domain haben sich geändert. domain, before, after
finding_alert Ein neues Problem, das wir sofort melden. severity, title, what, impact, action
grade_up Die Gesamtnote der Website ist um eine Stufe gestiegen (gute Nachrichten, wenn eingeschaltet). siteUrl, gradeFrom, gradeTo, scoreFrom, scoreTo, items, changesUrl
alert_summary Am Ende der Stunde, wenn es mehr als 10 Warnungen gab: alle zurückgehaltenen zusammen. items, timezone
channel_test Sie senden eine Testnachricht. settingsUrl, chat, accountName

Warnungen (alert) enthalten außerdem siteName (Name der Website in SitePrio) und – außer grade_up – dashboardUrl (die Website in SitePrio) und helpUrl (Hilfe anfordern).

Gut zu wissen

  • Zeiten wie startedAt, resolvedAt oder validTo sind ISO 8601 in UTC. timezone ist die Zeitzone des Kontos, in der text die Zeiten zeigt.
  • cause nennt die Ursache eines Ausfalls als Code, zum Beispiel TIMEOUT, CONN_REFUSED, DNS_NXDOMAIN, TLS_ERROR oder HTTP_5XX. Die Liste kann wachsen.
  • confidence: single_region – von einem Standort bestätigt, multi_region – auch von einem zweiten.
  • daysLeft ist negativ oder null, wenn Zertifikat oder Domain schon abgelaufen sind.
  • severity ist critical, high, medium, low oder info; title, what, impact und action sind in der Sprache des Kontos.
  • Nur manchmal da: selector, sectionMissing, pageGone und httpStatus bei keyword_missing, expired bei domain_expiring.
  • Diese Felder können auch null sein, das gehört zu ihrem Typ: helpUrl und legalDisclaimer bei finding_alert, daysLeft und expiresAt bei domain_expiring.

Beispiele

Die Beispiele stammen aus einem Konto mit der Sprache Deutsch. Hier eingerückt; gesendet wird der Body kompakt, ohne Leerzeichen und Zeilenumbrüche.

Beispiel 1 – die Website ist nicht erreichbar (incident_down):

{
  "type": "incident_down",
  "category": "alert",
  "timestamp": "2026-10-01T12:05:00.000Z",
  "text": "🔴 praxis-sommer.de ist nicht erreichbar\n\nIhre Website https://praxis-sommer.de/ ist seit 01.10.2026, 14:02 Uhr nicht erreichbar.\n\nWAS IST PASSIERT?\nIhr Server antwortet nicht (Zeitüberschreitung nach 15 Sekunden). Wir haben das dreimal innerhalb von 2 Minuten geprüft.\n\nWAS BEDEUTET DAS FÜR SIE?\nBesucher sehen gerade eine Fehlerseite statt Ihres Angebots. Online-Anfragen und -Buchungen sind nicht möglich.\n\nWAS KÖNNEN SIE JETZT TUN?\nPrüfen Sie, ob Ihr Hosting-Anbieter eine Störung meldet, und kontaktieren Sie die Person, die Ihre Website betreut. Oder wir kümmern uns darum.\n\nDetails ansehen: https://app.guard.findyour.dance/sites/019a3f5c-1c2d-7e3f-9a4b-5c6d7e8f9a0b\nHilfe anfordern (Notfall-Hilfe): https://app.guard.findyour.dance/sites/019a3f5c-1c2d-7e3f-9a4b-5c6d7e8f9a0b/help?service=emergency_help\n\nWir melden uns automatisch, sobald Ihre Website wieder erreichbar ist.\n\nTECHNISCHE DETAILS\nGeprüft von: 1 Standort (Deutschland)\nErgebnis: Server antwortete nicht (3 von 3 Prüfungen)\nBeginn: 01.10.2026, 14:02 (Europe/Berlin)\nUrsache (Code): TIMEOUT\nAdresse: https://praxis-sommer.de/\n\n— SitePrio",
  "data": {
    "siteName": "praxis-sommer.de",
    "siteUrl": "https://praxis-sommer.de/",
    "startedAt": "2026-10-01T12:02:00.000Z",
    "cause": "TIMEOUT",
    "timezone": "Europe/Berlin",
    "confidence": "single_region",
    "dashboardUrl": "https://app.guard.findyour.dance/sites/019a3f5c-1c2d-7e3f-9a4b-5c6d7e8f9a0b",
    "helpUrl": "https://app.guard.findyour.dance/sites/019a3f5c-1c2d-7e3f-9a4b-5c6d7e8f9a0b/help?service=emergency_help"
  }
}

Beispiel 2 – Zusammenfassung der Stunde (alert_summary):

{
  "type": "alert_summary",
  "category": "digest",
  "timestamp": "2026-10-01T12:05:00.000Z",
  "text": "2 weitere Warnungen in der letzten Stunde\n\nIn der letzten Stunde gab es mehr als 10 Warnungen. Damit Ihr Postfach nicht überläuft, fassen wir die weiteren hier zusammen:\n\n- 01.10.2026, 13:41 Uhr: 🔴 praxis-sommer.de ist nicht erreichbar\n- 01.10.2026, 13:52 Uhr: ✅ praxis-sommer.de ist wieder online\n\nDie Details sehen Sie in Ihrem Dashboard.\n\n— SitePrio",
  "data": {
    "items": [
      {
        "subject": "🔴 praxis-sommer.de ist nicht erreichbar",
        "at": "2026-10-01T11:41:07.000Z"
      },
      {
        "subject": "✅ praxis-sommer.de ist wieder online",
        "at": "2026-10-01T11:52:30.000Z"
      }
    ],
    "timezone": "Europe/Berlin"
  }
}

Beispiel 3 – Testnachricht (channel_test):

{
  "type": "channel_test",
  "category": "transactional",
  "timestamp": "2026-10-01T12:05:00.000Z",
  "text": "Testnachricht von SitePrio\n\nDieser Chat erhält ab jetzt Sofort-Warnungen zu den Websites von Praxis Sommer.\n\n— SitePrio",
  "data": {
    "settingsUrl": "https://app.guard.findyour.dance/notifications",
    "chat": true,
    "accountName": "Praxis Sommer"
  }
}

Zustellung und Wiederholungen

  • Zugestellt ist eine Nachricht, wenn Ihr System innerhalb von 15 Sekunden mit einem 2xx-Status antwortet, für die ganze Anfrage mit Verbindung und TLS. Den Inhalt der Antwort werten wir nicht aus.
  • Bei 408, 429, 5xx, Zeitüberschreitung oder Netzwerkfehler versuchen wir es erneut: insgesamt bis zu 5-mal, die Pausen nach dem gescheiterten Versuch sind 30 s, 2 Min., 8 Min. und 32 Min.. Danach geben wir die Nachricht auf.
  • Keinen neuen Versuch gibt es bei einer Weiterleitung (3xx: wir folgen ihr nicht), bei den übrigen 4xx-Codes und wenn die Adresse beim Senden auf eine interne IP-Adresse zeigt.
  • Verarbeiten Sie jede webhook-id nur einmal. Eine Nachricht kann noch einmal kommen, auch wenn Ihr System sie schon verarbeitet hat, etwa wenn die Antwort zu spät kam. webhook-timestamp, timestamp und die Signatur sind bei jedem Versuch neu.
  • Die Reihenfolge ist nicht garantiert: Eine Wiederholung kann nach der nächsten Nachricht kommen. Ordnen Sie nach der Zeit des Ereignisses in data.
  • Mehr als 10 Warnungen eines Kontos in einer Stunde: Die weiteren kommen am Ende der Stunde gesammelt als alert_summary.
  • Ein ausgeschalteter oder gelöschter Webhook bekommt nichts mehr, auch keine Wiederholungen; ebenso, wenn der Tarif keine Webhooks mehr enthält.

Darauf können Sie sich verlassen

Neue Felder in der Nachricht und in data, neue Arten (type) und neue Werte in Listen wie cause können hinzukommen. Bestehende Felder benennen wir nicht um, entfernen sie nicht und ändern nicht ihren Typ.

Ignorieren Sie deshalb unbekannte Felder und nehmen Sie auch eine unbekannte Art mit 2xx an, zeigen Sie zum Beispiel einfach text.