Mit Webhooks schickt turbopress dir Ereignisse an eine URL, statt dass du die API ständig abfragst. Du bekommst Bescheid, wenn ein Auftrag fertig oder fehlgeschlagen ist, wenn eine Website nicht erreichbar ist oder wieder läuft, wenn ein Plugin eine bekannte Sicherheitslücke hat, wenn eine Lizenz abläuft und wenn ein Wartungsbericht an deinen Kunden ging oder nicht ankam.
Voraussetzungen
- Webhooks sind für dein Hosting freigeschaltet (frage den Support, wenn die Berechtigung „Webhooks verwalten“ beim Erstellen eines API-Schlüssels fehlt).
- Du hast einen API-Schlüssel mit dem Ziel „Ganzes Konto“ und der Berechtigung „Webhooks verwalten“. Dazu kommt für jede Ereignisart das Leserecht: für Website-Ereignisse „Websites anzeigen“, für Plugin- und Lizenz-Ereignisse „Plugin-Bestand und Lizenzen anzeigen“, für Berichte „Wartungsberichte anzeigen“.
- Ereignisse zu Plugins, Lizenzen und Berichten gibt es nur, wenn dein Konto „Kunden & Websites“ im WP-Cockpit nutzt.
- Dein Endpunkt ist von außen über HTTPS erreichbar (gültiges Zertifikat, Port 443 oder ein Port ab 1024). Er trägt einen Domainnamen, keine IP-Adresse, und liegt nicht bei turbopress.
Webhook anlegen
Du brauchst dafür einen API-Schlüssel mit dem Ziel „Ganzes Konto“ und der Berechtigung „Webhooks verwalten“ (siehe Voraussetzungen). Das gilt im Panel genauso wie per API.
Im Panel
- Öffne im Panel über dein Konto-Menü API & KI-Zugriff und gehe zum Abschnitt Webhooks (auch direkt über Webhooks in der Seitenleiste).
- Klicke auf Webhook hinzufügen.
- Trage die Ziel-URL ein und wähle unter Senden mit Rechten von deinen API-Schlüssel. Kreuze die Ereignisse an, die du bekommen willst.
- Klicke auf Webhook anlegen. Das Secret (
whsec_…) siehst du nur dieses eine Mal. Kopiere es sofort in deinen Secret-Speicher. Ging es verloren, erneuerst du es später über Secret erneuern; das alte gilt dann sofort nicht mehr. - Klicke auf Test senden. Nach etwa einer Minute zeigt dir die Detailseite des Webhooks (Klick auf den Webhook) unter Zustellungen, ob dein Endpunkt geantwortet hat.
Per API
- Lege den Webhook mit deinem API-Schlüssel (in der Technik auch Token genannt) an (Beispiel mit der Demo-Domain):
curl -sS -X POST https://panel.turbopress.de/api/v1/webhooks \ -H "Authorization: Bearer $TP_API_TOKEN" -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"url": "https://hooks.elbtal-roesterei.de/turbopress", "events": ["site.down", "site.up", "operation.failed"]}'
- Die Antwort enthält das Secret (
whsec_…). Du siehst es nur dieses eine Mal. Speichere es sofort in deinem Secret-Speicher. Ging es verloren, erzeuge mitPOST /webhooks/<id>/rotate-secretein neues; das alte gilt dann sofort nicht mehr. - Teste den Webhook mit
POST /webhooks/<id>/test. Nach etwa einer Minute steht inGET /webhooks/<id>/deliveries, ob dein Endpunkt geantwortet hat.
Signatur prüfen
Jede Anfrage trägt den Header Turbopress-Signature mit t=<Unix-Zeit>,v1=<Hex>. v1 ist der HMAC-SHA256 über t, einen Punkt und den rohen Body, mit deinem Secret als Schlüssel. Prüfe die Signatur, bevor du den Inhalt verwendest:
- Lies den Body als rohe Bytes, bevor du ihn als JSON einliest.
- Lehne ab, wenn
tmehr als 5 Minuten von deiner Serveruhr abweicht. - Vergleiche in konstanter Zeit (
crypto.timingSafeEqualin Node.js,hash_equalsin PHP).
Node.js (der Body muss als Buffer ankommen, in Express mit express.raw({ type: 'application/json' })):
const crypto = require('node:crypto');
// secret: dein whsec_…, header: Wert von Turbopress-Signature,
// rawBody: der unveränderte Body (Buffer oder String), nowSeconds: aktuelle Unix-Zeit
function verifyTurbopress(secret, header, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
let t = null;
const candidates = [];
for (const part of String(header).split(',')) {
const i = part.indexOf('=');
if (i < 0) continue;
const key = part.slice(0, i).trim();
const value = part.slice(i + 1).trim();
if (key === 't') {
if (t !== null || !/^[1-9][0-9]{0,14}$/.test(value)) return false;
t = Number(value);
} else if (key === 'v1') {
if (!/^[0-9a-f]{64}$/.test(value)) return false;
candidates.push(value);
}
}
if (t === null || candidates.length === 0) return false;
if (Math.abs(nowSeconds - t) > 300) return false; // 5 Minuten Toleranz
const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
let ok = false;
for (const candidate of candidates) {
const given = Buffer.from(candidate, 'hex');
if (given.length === expected.length && crypto.timingSafeEqual(given, expected)) ok = true;
}
return ok;
}
PHP:
<?php
// $secret: dein whsec_…, $header: Wert von Turbopress-Signature,
// $body: der unveränderte Body (file_get_contents('php://input')), $now: time()
function turbopress_verify(string $secret, string $header, string $body, int $now): bool
{
$t = null;
$candidates = [];
foreach (explode(',', $header) as $part) {
$pos = strpos($part, '=');
if ($pos === false) {
continue;
}
$key = trim(substr($part, 0, $pos));
$value = trim(substr($part, $pos + 1));
if ($key === 't') {
if ($t !== null || preg_match('/^[1-9][0-9]{0,14}$/D', $value) !== 1) {
return false;
}
$t = (int) $value;
} elseif ($key === 'v1') {
if (preg_match('/^[0-9a-f]{64}$/D', $value) !== 1) {
return false;
}
$candidates[] = $value;
}
}
if ($t === null || $candidates === [] || abs($now - $t) > 300) { // 5 Minuten Toleranz
return false;
}
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$ok = false;
foreach ($candidates as $candidate) {
if (hash_equals($expected, $candidate)) {
$ok = true;
}
}
return $ok;
}
Zum Testen deiner Umsetzung: Mit dem Secret whsec_ gefolgt von 32-mal ab, t = 1793102400 und dem Body {"id":"evt_x"} lautet der Header t=1793102400,v1=480a7e102c35b05320180762c6f12c97c64b02202700defbc05a63ea55d7ba3a.
Antworten und Wiederholungen
- Antworte innerhalb von 10 Sekunden mit einem
2xx-Status. Weiterleitungen werden nicht verfolgt. - Schlägt die Zustellung fehl, versucht turbopress es bis zu siebenmal erneut (nach 1 Minute, 5 Minuten, 30 Minuten, 2, 6, 12 und 24 Stunden), insgesamt also acht Versuche.
- Ein Ereignis kann mehr als einmal ankommen. Speichere die ID aus dem Header
Turbopress-Deliveryund verarbeite eine bekannte ID nicht noch einmal; antworte trotzdem mit2xx. - Die Reihenfolge ist nicht garantiert.
Wann ein Webhook abgeschaltet wird
Kommt über 3 Tage lang nichts mehr an und sind mindestens 20 Zustellungen endgültig gescheitert, schaltet turbopress den Webhook ab und schickt dem Kontoinhaber eine Mail. Behebe den Fehler an deinem Endpunkt und schalte den Webhook danach wieder ein: im Panel mit dem Knopf Wieder einschalten (in der Liste oder auf der Detailseite des Webhooks) oder über die API mit PATCH /webhooks/<id> und {"active": true} wieder ein. Ereignisse aus der Zwischenzeit werden nicht nachgeliefert. Im Panel kannst du Webhooks anlegen, testen, ansehen (Zustellungen mit Zeit, Ereignis, Ergebnis und Versuchen), pausieren, wieder einschalten, das Secret erneuern, Ziel-URL und Ereignisse ändern und Webhooks löschen. Der API-Schlüssel eines Webhooks lässt sich nicht ändern; lege dafür einen neuen Webhook an. Wurde der API-Schlüssel widerrufen, kannst du den Webhook nur noch ansehen oder löschen.
Gut zu wissen
- Ein Webhook bekommt nur Ereignisse, die nach seiner Anlage eintreten.
- Fällt die Zustellung länger als eine Stunde aus, gehen die Ereignisse dieser Zeit verloren. Wenn du keins verpassen darfst, gleiche zusätzlich über die Leserouten der API ab.
site.downkommt erst, wenn die Überwachung den Ausfall bestätigt hat (bei einer vorläufigen Start-Adresse nach der Karenz von einer Stunde, auch wenn der Ausfall dann schon länger läuft), und unabhängig davon, ob du die Ausfall-Mail abgeschaltet hast.site.upkommt nur zusammen mitsite.down: Abonniere beide Arten.- Alle Zeitstempel haben das Format
2026-10-29T03:12:00+00:00(UTC). - Höchstens 10 Webhooks pro Konto, höchstens 60 Zustellungen pro Minute.
- Die Absenderadressen von turbopress nennen wir nicht; verlasse dich auf die Signatur.
Typische Probleme
- **400
invalid_webhook_url:** Die URL entspricht den Regeln nicht (nurhttps://, Port 443 oder ab 1024, ein Domainname statt einer IP-Adresse, keine Domain von turbopress).error.fieldisturl. - **403
permission_denied:** Dem API-Schlüssel fehlt „Webhooks verwalten“ oder das Leserecht für eine Ereignisart, oder er hat nicht das Ziel „Ganzes Konto“. - **403
feature_not_enabled:** Für Plugin-, Lizenz- und Berichts-Ereignisse ist „Kunden & Websites“ nicht aktiv. - **404
webhook_not_found:** Die ID stimmt nicht, oder der Webhook gehört zu einem anderen API-Schlüssel. - **409
webhook_limit:** Du hast schon 10 Webhooks; lösche einen. - **409
secret_not_replayable:** Du hastPOST /webhooksmit demselbenIdempotency-Keywiederholt. Der Webhook besteht schon (sieheGET /webhooks); erzeuge mitrotate-secretein neues Secret. - **503
feature_unavailable:** Webhooks sind derzeit nicht verfügbar. - **In der Zustellungsliste steht
address_rejected:** Der Domainname löst nicht auf oder zeigt auf eine nicht öffentliche Adresse. - **
tls_failed:** Das Zertifikat deines Endpunkts ist abgelaufen, passt nicht zum Namen oder die Kette ist unvollständig. - **
http_status:** Dein Endpunkt hat nicht mit2xxgeantwortet (auch eine Weiterleitung zählt als Fehler).
Weitere Anleitungen
API-Schlüssel erstellen und widerrufen · Agentur-API · OpenAPI-Referenz · Fehler und Timeouts