Webhooks einrichten

Empfange signierte JSON-Ereignisse von octoja an deinem eigenen HTTPS-Endpunkt.

Geschrieben von Erdinc Akay

Zuletzt aktualisiert Vor 26 Tagen

Ein Webhook ist ein HTTP-POST, den octoja an eine von dir kontrollierte URL sendet. Jede Zustellung ist eine signierte JSON-Anfrage — dein Empfänger kann also prüfen, dass sie wirklich von octoja stammt. Nutze Webhooks, um octoja-Ereignisse — von dir ausgelöste Test-Zustellungen und Asset-Inventar-Pushes — in deine eigenen Dienste und Automatisierungen zu übernehmen.

Voraussetzungen

  • Du brauchst die Berechtigung Integrationsverwaltung. Mit ihr kannst du Webhooks für den Mandanten anlegen, bearbeiten und löschen. Berechtigungen werden unter Administration → Gruppen vergeben.
  • Du brauchst eine öffentlich erreichbare URL, die HTTPS-POST-Anfragen mit einem JSON-Body annimmt — zum Beispiel einen HTTPS-Handler in deinem eigenen Dienst oder den Endpunkt einer Automatisierungsplattform.

Schritte

  1. Gehe zu Administration → Integrationen und klicke auf der Karte Webhooks auf Webhooks verwalten.
  2. Klicke auf Webhook hinzufügen.
  3. Fülle den Dialog aus:
FeldBeschreibung
NameAnzeigename für diesen Webhook. Freitext — wähle etwas, das den Empfänger identifiziert (z. B. „PagerDuty-Alarme")
URLDer HTTPS-Endpunkt, an den octoja Ereignisse postet. Muss eine öffentlich erreichbare HTTPS-URL sein.
Dialog „Webhook hinzufügen" mit einem Feld Name, einem Feld URL und der Schaltfläche Erstellen.
  1. Klicke auf Erstellen. octoja generiert ein Signatur-Secret und zeigt es einmalig im Dialog Webhook-Secret speichern an. Kopiere es jetzt — du kannst es später nicht erneut einsehen. Hinterlege es in der Konfiguration deines Empfängers als HMAC-Verifizierungsschlüssel und klicke dann auf Gespeichert. octoja bringt dich direkt zur Detailseite des neuen Webhooks.
  2. Aktiviere den Webhook. Neue Webhooks werden im Zustand Deaktiviert angelegt und stellen nichts zu, bis du sie einschaltest. Lege den Schalter oben auf der Detailseite um, sodass der Status daneben Aktiv anzeigt.
  3. Klicke in der Kopfzeile auf Test senden, um ein synthetisches Test-Ereignis an deinen Endpunkt zuzustellen, und öffne dann den Tab Historie, um zu prüfen, dass die Zustellung erfolgreich war (Status, Antwortcode und Dauer werden pro Versuch angezeigt).

Das war's — der Webhook ist aktiv und verifiziert. Die folgenden Abschnitte beschreiben das Wire-Format, das dein Empfänger verarbeiten muss, sowie den laufenden Betrieb (Erneut senden, Secret-Rotation, Retries).

Welche Ereignisse octoja sendet

Jede Zustellung nennt ihren Ereignistyp im Header X-Octoja-Event:

EreignisWird ausgelöst, wenn
WebhookTestDu auf der Detailseite des Webhooks auf Test senden klickst. Wird auch bei deaktiviertem Webhook zugestellt, damit du deinen Empfänger vor dem Live-Schalten prüfen kannst
InventorySnapshotEine vollständige Asset-Inventar-Basis (Kunden, Standorte, Geräte, Hardware) gepusht wird, sobald die Inventar-Zustellung für einen Webhook startet
InventoryUpdateEin stündliches Batch aller Inventar-Änderungen seit dem letzten Push gesendet wird — geänderte Geräte, entfernte Geräte und die aktuelle Kundenliste
CheckFailedEin Monitoring-Check überschreitet seine Alarmschwelle und meldet ein kritisches Ergebnis. Wird zugestellt, wenn der Webhook als Alarmkanal für diesen Check ausgewählt ist
CheckWarningEin Monitoring-Check überschreitet seine Alarmschwelle und meldet ein Warnungs-Ergebnis. Wird zugestellt, wenn der Webhook als Alarmkanal für diesen Check ausgewählt ist
CheckRecoveredEin Monitoring-Check, der zuvor alarmiert hat, erholt sich wieder. Wird zugestellt, wenn der Webhook als Alarmkanal für diesen Check ausgewählt ist
automationEin Automatisierungs-Workflow erreicht einen Schritt, der an diesen Webhook sendet. Wird zugestellt, wenn der Webhook das Ziel des Webhook-senden-Schritts einer Automatisierung ist

Die Spalte Ereignisse auf der Webhooks-Listenseite zeigt, welche Ereignisse ein Webhook für die Inventar-Zustellung abonniert hat. Neu angelegte Webhooks starten ohne Inventar-Abonnement, und die aktuelle Version bietet kein Bedienelement, um es zu ändern — Test-Zustellungen und das erneute Senden funktionieren unabhängig davon. Die Check-Monitoring-Ereignisse (CheckFailed, CheckWarning, CheckRecovered) und das Ereignis automation hängen nicht von diesem Abonnement ab: Sie kommen an, sobald der Webhook als Alarmkanal für einen Monitoring-Check oder als Ziel eines Automatisierungs-Schritts ausgewählt ist. Baue deinen Empfänger so, dass er anhand des Headers X-Octoja-Event verzweigt und unbekannte Ereignistypen ignoriert.

Request-Format

Jede Zustellung ist ein einzelner HTTPS-POST mit einem JSON-Body. Die Anfrage trägt folgende Header:

HeaderWert
X-Octoja-EventDer Ereignistyp — zum Beispiel WebhookTest
X-Octoja-DeliveryEine eindeutige GUID, die diese Zustellung identifiziert. Nutze sie für Idempotenz auf deiner Seite
X-Octoja-TimestampUnix-Sekunden zum Signierzeitpunkt. Immer nur wenige Sekunden vom „Jetzt" entfernt
X-Octoja-Signaturesha256=<hex> — HMAC-SHA256 über die Zeichenkette {timestamp}.{body} mit deinem Webhook-Secret
User-Agentoctoja-Webhooks/1.0
Content-Typeapplication/json

Signatur verifizieren

Validiere X-Octoja-Signature immer, bevor du der Payload vertraust. Die Signatur ist der HMAC-SHA256 der wörtlichen Zeichenkette <timestamp>.<body> (mit Punkt als Trenner), berechnet mit dem Secret deines Webhooks.

Node.js-Beispiel:

const crypto = require('crypto');const secret = process.env.OCTOJA_WEBHOOK_SECRET;const timestamp = req.header('X-Octoja-Timestamp');const signature = req.header('X-Octoja-Signature'); // "sha256=..."const rawBody = req.rawBody.toString('utf8');const expected = 'sha256=' + crypto  .createHmac('sha256', secret)  .update(`${timestamp}.${rawBody}`)  .digest('hex');if (signature !== expected) return res.status(401).end();

Vergleiche die Signatur immer mit einem konstantzeitigen Vergleich (crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python), um Timing-Seitenkanal-Lecks zu vermeiden.

Retry und Auto-Deaktivierung

Wenn der Empfänger mit einem Nicht-2xx-Status antwortet oder die Anfrage abläuft, versucht octoja es automatisch erneut:

VersuchVerzögerung nach dem vorherigen Versuch
21 Minute
35 Minuten
430 Minuten
52 Stunden
612 Stunden
724 Stunden
  • Eine Antwort im 4xx-Bereich (Unauthorized, Bad Request, Not Found usw.) wird als dauerhaftes Empfänger-Problem behandelt und nicht wiederholt — die Zustellung schlägt sofort endgültig fehl.
  • Eine Antwort im 5xx-Bereich, ein Netzwerkfehler oder ein 10-Sekunden-Timeout pro Versuch löst den Retry-Zeitplan aus.
  • Nach 20 aufeinanderfolgenden fehlgeschlagenen Zustellungen wird der Webhook automatisch deaktiviert. Du siehst das auf der Listenseite (Statusanzeige neben dem Namen) und auf der Detailseite (der Schalter zeigt Deaktiviert). Behebe den Empfänger und schalte den Schalter dann wieder ein, um die Zustellung fortzusetzen.

Empfänger testen

Klicke auf der Detailseite eines Webhooks auf Test senden, um sofort ein synthetisches WebhookTest-Ereignis zuzustellen. Damit überprüfst du, ob dein Endpunkt erreichbar ist, die URL korrekt ist und die Signaturverifizierung funktioniert.

Testereignisse umgehen den Aktivierungsschalter (du kannst also auch einen deaktivierten Webhook testen) und zählen nicht zur Auto-Deaktivierungsgrenze (Testen gegen eine kaputte URL kann deinen eigenen Webhook also nicht deaktivieren).

Eine vergangene Zustellung erneut senden

Der Tab Historie auf der Detailseite listet die Zustellversuche der letzten 30 Tage mit Ereignis, Status, Versuchsnummer und Dauer und lässt sich nach Ereignistyp, Status und Zeitraum filtern. Klicke bei einer Zustellung auf Erneut senden, um den ursprünglichen Request-Body erneut an deinen Endpunkt zu schicken. Nützlich, wenn dein Empfänger zeitweise nicht erreichbar war und du verpasste Ereignisse manuell nachschieben möchtest.

Secret rotieren

Wenn ein Secret durchsickert, öffne die Detailseite des Webhooks und klicke im Tab Konfiguration auf Secret rotieren. Bestätige den Dialog Signatur-Secret rotieren? — octoja generiert ein neues Secret und zeigt es, wie bei der Erstellung, einmalig in einem Dialog an. Kopiere es, bevor du den Dialog schließt, denn es lässt sich später nicht erneut einsehen.

Der Dialog erwähnt eine 24-stündige Übergangsfrist für das alte Secret. Plane die Rotation trotzdem als harten Wechsel: Stelle deinen Empfänger sofort nach dem Bestätigen auf das neue Secret um, denn jede Zustellung, die octoja ab diesem Zeitpunkt signiert, verwendet den neuen Schlüssel.

Tipps

  • Benutzerdefinierte Header — die Karte Benutzerdefinierte Header im Tab Konfiguration enthält feste Header, die octoja bei jeder Zustellung mitsendet (zum Beispiel ein statisches API-Token). Sie werden wörtlich neben den X-Octoja-*-Headern gesendet und fließen nicht in die Signaturberechnung ein.
  • Idempotenz — nutze X-Octoja-Delivery als Idempotenzschlüssel auf deiner Seite. Wenn ein Retry erfolgreich ist, nachdem der ursprüngliche Versuch abgelaufen ist, siehst du dieselbe Zustellungs-ID zweimal.
  • Replay-Schutz — verwerfe Anfragen, deren X-Octoja-Timestamp älter als 5 Minuten ist, um das Replay-Risiko zu begrenzen.
  • Fehlersuche: Wenn keine Zustellungen ankommen, prüfe zuerst, ob der Webhook Aktiv ist — neue Webhooks starten deaktiviert. Klicke dann auf Test senden, um die genaue Antwort zu sehen, die octoja erhält, verifiziere, dass dein Empfänger 2xx zurückgibt (jeder 4xx schlägt dauerhaft fehl), und prüfe Produktstatus & Bekannte Einschränkungen.

Siehe auch: Alarme an einen Microsoft-Teams-Kanal senden — octoja-Benachrichtigungen via Power Automate in einen Teams-Kanal posten.