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.
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.
Was ankommt
Zu jeder Nachricht schickt SitePrio eine POST-Anfrage an Ihre Adresse: im Body ein JSON-Objekt in UTF-8, dazu diese Kopfzeilen.
| Kopfzeile | Wert | Bedeutung |
|---|---|---|
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:
| Feld | Inhalt |
|---|---|
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,resolvedAtodervalidTosind ISO 8601 in UTC.timezoneist die Zeitzone des Kontos, in dertextdie Zeiten zeigt. causenennt die Ursache eines Ausfalls als Code, zum BeispielTIMEOUT,CONN_REFUSED,DNS_NXDOMAIN,TLS_ERRORoderHTTP_5XX. Die Liste kann wachsen.confidence:single_region– von einem Standort bestätigt,multi_region– auch von einem zweiten.daysLeftist negativ odernull, wenn Zertifikat oder Domain schon abgelaufen sind.severityistcritical,high,medium,lowoderinfo;title,what,impactundactionsind in der Sprache des Kontos.- Nur manchmal da:
selector,sectionMissing,pageGoneundhttpStatusbeikeyword_missing,expiredbeidomain_expiring. - Diese Felder können auch
nullsein, das gehört zu ihrem Typ:helpUrlundlegalDisclaimerbeifinding_alert,daysLeftundexpiresAtbeidomain_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-idnur 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,timestampund 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.