Ausgehende Webhooks — Dokumentation

Ein ausgehender Webhook ist eine Nachricht, die das Panel an eine Adresse von Ihnen sendet, wenn mit einem Hosting-Konto etwas geschieht, damit ein anderes System reagieren kann: Ihre eigene Abrechnung, ein Chat-Kanal, eine Tabelle, ein Provisionierungsskript.

Webhooks stehen Administratoren und Resellern zur Verfügung. Ein Administrator erfährt von jedem Konto. Ein Reseller erfährt nur von den Konten, die diesem Reseller gehören. Kunden und API-Tokens können keine anlegen: Webhooks werden im Panel selbst eingerichtet, in der eigenen Sitzung einer Person, damit ein geleaktes Token nie zu einem dauerhaften Feed der Panel-Ereignisse werden kann.

Einen hinzufügen

Öffnen Sie die Sicherheitsseite Ihres Kontos (Administrator: Sicherheit; Reseller: Login Security) und suchen Sie unterhalb der API-Tokens Webhooks.

Geben Sie die Adresse ein, zum Beispiel https://example.com/hooks/panel.
Haken Sie die gewünschten Ereignisse an.
Klicken Sie auf Webhook hinzufügen.

Das Panel zeigt ein Signatur-Geheimnis (es beginnt mit whsec_) einmal an. Kopieren Sie es jetzt. Es wird verschlüsselt gespeichert und kann nicht erneut angezeigt werden; wenn Sie es verlieren, löschen Sie den Webhook und legen einen neuen an.

Jede Person kann höchstens 10 Webhooks haben.

Die Adresse

Sie muss mit https:// beginnen. Ein einfaches http:// wird abgelehnt, weil der Aufruf Kontodetails enthält.
Sie darf keinen Benutzernamen und kein Passwort enthalten. Prüfen Sie stattdessen die Signatur.
Sie darf höchstens 500 Zeichen lang sein.
Sie muss im öffentlichen Internet liegen. Adressen auf diesem Server, in einem privaten Netzwerk, auf der Loopback-Schnittstelle oder im Metadatenbereich des Cloud-Anbieters werden abgelehnt, sowohl beim Speichern der Adresse als auch noch einmal in dem Moment, in dem sich das Panel verbindet (ein Hostname, der später auf eine private Adresse zeigt, funktioniert also ebenfalls nicht).
Weiterleitungen werden nicht verfolgt. Geben Sie die endgültige Adresse an.

Die Ereignisse

Ereignis	Wird gesendet, wenn
`account.created`	ein Hosting-Konto erstellt wird
`account.suspended`	ein Konto gesperrt wird
`account.unsuspended`	ein gesperrtes Konto wieder aktiviert wird
`account.deleted`	ein Konto gelöscht wird
`account.activity`	sonstige Aktivität auf einem Konto stattfindet

Eine Schaltfläche Testen bei jedem Webhook sendet ein Ereignis namens ping, damit Sie sehen, dass Ihre Adresse antwortet. Es kann immer nur ein Test warten.

Was gesendet wird

Jeder Aufruf ist ein HTTP-POST mit einem JSON-Body:

{
  "event": "account.created",
  "at": "2026-10-23T08:15:00Z",
  "account": { "id": 42, "username": "example", "domain": "example.com" },
  "detail": "short text about what happened"
}

at ist eine UTC-Zeit. Das Ereignis ping hat die Form {"event":"ping","at":"…","webhook_id":7}.

Diese Header gehören zu jedem Aufruf:

Header	Bedeutung
`X-Nimbopanel-Event`	Der Ereignisname, zum Beispiel `account.created`
`X-Nimbopanel-Delivery`	Eine Nummer, die diese Zustellung kennzeichnet. Eine Wiederholung derselben Zustellung behält dieselbe Nummer; nutzen Sie sie also, um Duplikate zu ignorieren
`X-Nimbopanel-Timestamp`	Wann der Aufruf signiert wurde, in Unix-Sekunden
`X-Nimbopanel-Signature`	`sha256=` gefolgt von der Signatur (siehe unten)
`Content-Type`	`application/json`
`User-Agent`	`Nimbopanel-Webhook/1`

Die Signatur prüfen

Jeder kann eine Anfrage an Ihre Adresse senden. Die Signatur zeigt Ihnen, dass ein Aufruf von Ihrem Panel kam.

Die Signatur ist ein HMAC-SHA256 in Hex-Schreibweise über den Zeitstempel, einen Punkt und den Roh-Body genau so, wie er empfangen wurde, gebildet mit Ihrem Signatur-Geheimnis:

X-Nimbopanel-Signature == "sha256=" + hex( HMAC_SHA256( secret, X-Nimbopanel-Timestamp + "." + body ) )

Prüfen Sie in dieser Reihenfolge:

Berechnen Sie den obigen Wert aus dem rohen Request-Body (vor jedem JSON-Parsing oder Umformatieren).
Vergleichen Sie ihn mit dem Header in einem zeitkonstanten Vergleich.
Weisen Sie den Aufruf ab, wenn der Zeitstempel mehr als 5 Minuten von Ihrer Uhr abweicht. Das verhindert, dass jemand einen alten Aufruf erneut einspielt.
Nutzen Sie X-Nimbopanel-Delivery, um eine Zustellung zu ignorieren, die Sie schon bearbeitet haben.

Beispiel in PHP:

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_NIMBOPANEL_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_NIMBOPANEL_SIGNATURE'] ?? '';
$want = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($want, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(401);
    exit;
}

Beispiel in Node.js:

const crypto = require('crypto');
function valid(rawBody, headers, secret) {
  const ts = headers['x-nimbopanel-timestamp'] || '';
  const want = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const got = headers['x-nimbopanel-signature'] || '';
  return got.length === want.length
    && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want))
    && Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
}

Antworten, Wiederholungen und Pausieren

Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Alles andere zählt als Fehler.
Ein fehlgeschlagener Aufruf wird nach 1 Minute erneut versucht, dann nach 5 Minuten, 30 Minuten und 2 Stunden. Das sind insgesamt fünf Versuche, verteilt über etwa zweieinhalb Stunden; danach wird die Zustellung als fehlgeschlagen markiert.
Aufrufe an eine Adresse werden nacheinander gesendet, die ältesten zuerst. Eine Zustellung, die auf eine Wiederholung wartet, hält neuere nicht zurück; verlassen Sie sich also nicht darauf, dass Ereignisse in strenger Reihenfolge eintreffen. Eine langsame Adresse hält nur sich selbst auf.
Nach 50 fehlgeschlagenen Zustellungen in Folge pausiert der Webhook: Für ihn werden keine neuen Ereignisse mehr eingereiht. Ein erfolgreicher Test setzt den Zähler zurück, und die Ereignisse fließen wieder.
Pro Webhook warten höchstens 200 nicht zugestellte Aufrufe. Darüber hinaus werden weitere Ereignisse für ihn nicht eingereiht, bis einige zugestellt wurden oder fehlgeschlagen sind.
Das Panel behält für jeden Webhook die neuesten 50 abgeschlossenen Zustellungen samt der erhaltenen Antwort, damit Sie sehen können, was fehlgeschlagen ist. Die jüngsten werden unter dem Webhook aufgelistet.

Zeigt das Panel statt eines Status einen Grund an, ist es einer dieser: Die Adresse liegt nicht im öffentlichen Internet, keine Antwort innerhalb von 10 Sekunden, der Hostname existiert nicht, das HTTPS-Zertifikat ist nicht gültig, oder das Panel konnte sich nicht verbinden.

Gute Gewohnheiten

Antworten Sie schnell mit 200 und erledigen Sie die eigentliche Arbeit danach. Ein Empfänger, der länger als 10 Sekunden braucht, sieht wie ein Fehler aus und bekommt dasselbe Ereignis erneut.
Verkraften Sie dieselbe Zustellung zweimal ohne Schaden. Wiederholungen und Netzwerkfehler machen Duplikate möglich.
Halten Sie das Geheimnis aus Ihrem Code-Repository heraus. Wenn es geleakt wird, löschen Sie den Webhook und legen einen neuen an.

Siehe auch: Reseller-Anleitung · Fehlerbehebung