Webhooks

Owner und Admins verwalten Endpunkte auf der Dashboard-Seite Webhooks unter /integrations/webhooks. Der Docs-Button unten rechts öffnet diese Anleitung. Payload, Header, Signatur und Wiederholungen stehen unter Webhooks und Kalender. Diese Seite ersetzt die Event-Referenz nicht.

Ziel

Ein Aktiver HTTPS-Endpunkt empfängt die gewählten Events, sobald die Änderung gespeichert ist. Alle Events empfängt alle aktuellen und zukünftigen Typen, einschließlich Buchungen aus dem Online-Bezahlvorgang und späterer Statuswechsel. Die vollständige Liste steht in der Event-Referenz.

Voraussetzungen

Benötigte Rolle: Owner oder Admin. Trainer:in sieht Integrationen nicht. Ohne Recht erscheint Keine Berechtigung für Integrationen.
Ein Plan mit Entwicklerfunktionen: Studio oder Business. Free und Solo enthalten API, ICS und Webhooks nicht.
Eine öffentlich erreichbare HTTPS-URL mit gültigem Zertifikat. Keine Benutzerdaten in der URL, kein localhost, keine privaten Netze, höchstens 2.048 Zeichen.
Du brauchst einen Empfänger, der innerhalb von 10 Sekunden mit einem Status 2xx antwortet und dieselbe Event-ID nur einmal verbucht.

Schritte

1. Webhooks öffnen

Öffne in der Gruppe Integrationen den Eintrag Webhooks. Die feste Route ist https://app.orbinaut.ccl-dev.com/integrations/webhooks.
Überschrift Webhooks. Untertitel: Workspace-Ereignisse signiert an externe Tools senden. Die Seite bleibt der Einstieg; der Katalog gilt für alle abonnierten Typen.
Ohne Einträge: Noch kein Webhook.
Die Tabelle listet Webhook, Events, Status, Letztes Event und Aktionen.

2. Endpunkt anlegen

Webhook erstellen öffnet eine eigene Seite unter /integrations/webhooks/new. Sie führt in drei Schritten durch die Anlage: Ziel, Events, Secret sichern. Die Schrittleiste oben zeigt den aktuellen Schritt; Abbrechen bringt dich ohne Änderung zurück zur Liste.

Ziel. Trage den Namen ein, zum Beispiel wie der Platzhalter Zapier Buchungen, und die HTTPS-URL deines Empfängers. Weiter prüft beides sofort: Ohne Namen erscheint Gib einen Namen ein., eine Adresse ohne https:// am Anfang meldet Die URL muss mit https:// beginnen. Erst ein gültiges Ziel öffnet den nächsten Schritt. Die vollständige Prüfung der Adresse übernimmt Orbinaut beim Anlegen (siehe unten).
Events. Kein Event ist vorausgewählt; Webhook erstellen bleibt gesperrt, bis mindestens ein Event gewählt ist. Alle Events speichert * und empfängt alle aktuellen und zukünftigen Typen; setze das Häkchen bewusst, denn jedes Event sendet Daten nach außen. Darunter listet eine Tabelle den ganzen Katalog mit Ressource, Event und Beschreibung. Nach Event suchen filtert nach Typ oder Bezeichnung, das Menü Alle Ressourcen grenzt auf eine Ressource ein, Pro Seite blättert in Schritten von 10, 25 oder 50. Ein Häkchen je Zeile wählt das Event; das Häkchen im Tabellenkopf wählt alle sichtbaren Zeilen. Sobald du bei gesetztem Alle Events ein Häkchen entfernst, gilt nur noch die ausdrückliche Auswahl. Mindestens ein Event ist nötig. Optional kannst du Teilnehmerdaten mitsenden aktivieren: Fügt Namen und E-Mail zum Event hinzu. Ohne Häkchen bleibt das Event ohne personenbezogene Daten. Zurück führt zum Ziel, Webhook erstellen legt den Endpunkt an. Erfolg: Webhook wurde erstellt.
Secret sichern. Der letzte Schritt zeigt das Signatur-Secret genau einmal. Hinweis auf der Seite: Dieses Secret siehst du nur jetzt. Kopieren übernimmt es in die Zwischenablage; darunter steht, wie du x-orbinaut-signature prüfst. Die Schritte Ziel und Events sind jetzt gesperrt, weil der Endpunkt bereits existiert. Bestätige mit Sicher gespeichert; die Seite kehrt zur Webhook-Liste zurück.

Ohne passenden Plan zeigt auch die Seite Webhook erstellen nur den Hinweis Webhooks sind derzeit gesperrt und Zurück zu Webhooks.

Lehnt Orbinaut die URL ab, erscheint Der Webhook konnte nicht erstellt werden. Ursache ist eine URL, die gegen eine Regel verstößt: kein https://, Benutzerdaten in der URL, localhost oder eine Endung wie .local, .internal, .home, .lan, eine private IP-Adresse, ein Hostname, der auf eine private Adresse auflöst, oder ein Incoming-Webhook von Discord oder Slack. Diese Chat-Webhooks erwarten ein anderes JSON-Format und können Orbinaut-Events nicht annehmen. Orbinaut prüft die DNS-Auflösung schon beim Speichern. Zum Testen eignet sich ein HTTPS-Empfänger, der JSON entgegennimmt und mit einem Erfolgsstatus antwortet.

Das Secret erscheint nur einmal. In Beispielen kein erfundenes Secret verwenden. Die Prüfung selbst steht in der Event-Referenz.

3. Secret, Zustellung und Fehler

Jede abonnierte Änderung erzeugt für jeden aktiven Endpunkt eine Zustellung, in derselben Transaktion wie die Änderung. Ein Worker prüft alle 5 Sekunden auf fällige Zustellungen und sendet POST als JSON mit den Headern x-orbinaut-event-id, x-orbinaut-timestamp und x-orbinaut-signature. Das Event kommt in der Regel wenige Sekunden nach der Änderung an.

In der Tabelle:

Spalte	Bedeutung
Events	Alle Events oder {n} Events, plus Teilnehmerdaten oder Ohne personenbezogene Daten.
Status	Aktiv oder Deaktiviert. Bei gesperrtem Plan zusätzlich Vom Plan blockiert.
Letztes Event	Zugestellt, Versuch {n}, Endgültig fehlgeschlagen oder Noch keins

Letztes Event zeigt die jüngste Zustellung dieses Endpunkts. Versuch {n} heißt: {n} Versuche sind gescheitert, der nächste ist geplant.

Der Name in der Tabelle oder Details öffnen führt zur Detailseite des Endpunkts unter /integrations/webhooks/{id}. Oben steht die Karte Endpunkt mit Status, HTTPS-URL (mit URL kopieren), der Event-Auswahl als Liste, Secret-Version, Angelegt und Zuletzt geändert. Darunter listet Zustellungen das Protokoll dieses Endpunkts: Eventtyp, Versuche, Zeitpunkt und Fehlercode, neueste zuerst, mit Weitere laden für ältere Einträge. Die Liste aktualisiert sich von selbst, solange die erste Seite sichtbar ist. Bei Endgültig fehlgeschlagen oder nach dem achten Versuch steht Erneut senden. Testevent senden legt ein Event ping nur für diesen Endpunkt an; bei einem deaktivierten Endpunkt ist der Button gesperrt. Eine unbekannte Adresse zeigt Webhook nicht verfügbar und Zurück zu Webhooks.

Fehlgeschlagene Zustellungen wiederholt Orbinaut mit Backoff, höchstens 8 Versuche mit einem Timeout von 10 Sekunden je Versuch. Die Wartezeit beginnt bei 5 Sekunden und verdoppelt sich; zwischen dem ersten und dem achten Versuch liegen rund 11 Minuten. Als Erfolg zählt nur ein Status 2xx. Orbinaut folgt keinen Weiterleitungen. Alle Versuche desselben Events nutzen dieselbe x-orbinaut-event-id, aber einen neuen Timestamp und eine neue Signatur. Empfänger müssen idempotent verarbeiten. Nach dem achten Fehlversuch steht Endgültig fehlgeschlagen, bis du Erneut senden wählst.

Zugestellte Zeilen bleiben 30 Tage sichtbar, endgültig fehlgeschlagene 90 Tage. Offene Zustellungen bleiben bestehen.

Unten in der Tabelle und auf der Detailseite stehen HMAC-Signatur: <timestamp>.<raw-body> und Event-ID: x-orbinaut-event-id.

4. Secret rotieren, deaktivieren, ersetzen

Die Aktionen stehen in der Tabelle als Symbole und auf der Detailseite als Buttons.

Secret rotieren fragt Signatur-Secret rotieren? Das alte Secret ist danach ungültig. Das neue Secret erscheint genau einmal: Signatur-Secret wurde rotiert. Das alte Secret ist ungültig. Aktualisiere die Signaturprüfung im Zielsystem. Auf der Detailseite steigt danach die Secret-Version. Auch Wiederholungen bereits wartender Events sind ab jetzt mit dem neuen Secret signiert.
Deaktivieren fragt Webhook deaktivieren? Zustellungen stoppen sofort, die Konfiguration bleibt erhalten. Erfolg: Webhook wurde deaktiviert. Buchungen während der Deaktivierung erzeugen für diesen Endpunkt kein Event und werden nicht nachgeliefert. Bereits wartende Zustellungen pausieren.
Aktivieren nimmt den Endpunkt wieder in Betrieb: Webhook wurde aktiviert. Pausierte Zustellungen laufen sofort weiter.

Bearbeiten gibt es nicht: Ziel, Events und Teilnehmerdaten eines Endpunkts sind fest, das Signatur-Secret gehört zu genau dieser Verbindung. Für ein anderes Ziel oder andere Events legst du mit Webhook erstellen einen neuen Webhook an, hinterlegst dessen Secret im Zielsystem und deaktivierst den alten. Löschen gibt es ebenfalls nicht. Deaktivieren ist der Endzustand eines Endpunkts.

Plan-Sperre

Enthält der Plan keine Webhooks mehr oder ist das Abonnement nicht aktiv, zeigt die Seite Webhooks sind derzeit gesperrt. Die Tabelle trägt das Badge Vom Plan blockiert. Der Text nennt den Grund:

Text	Bedeutung
Webhooks gehören nicht mehr zu deinem Plan. Ab {plan} sind sie wieder verfügbar. Bestehende Endpunkte senden bis dahin keine Ereignisse mehr.	Planwechsel nach unten; {plan} ist der nächste Plan mit Webhooks
Webhooks gehören nicht mehr zu deinem Plan. Bestehende Endpunkte senden keine Ereignisse mehr, und Secret rotieren oder Aktivieren ist gesperrt. Ausschalten bleibt möglich.	Plan ohne Webhooks ohne Upgrade-Pfad
Dein Abonnement ist derzeit nicht aktiv. Solange es pausiert ist, sendet Orbinaut keine Webhook-Ereignisse, und Secret rotieren oder Aktivieren ist gesperrt.	Abonnement nicht aktiv

Gesperrt sind Webhook erstellen, Secret rotieren, Testevent senden und Aktivieren. Deaktivieren bleibt möglich. Während der Sperre entstehen keine Events; bereits wartende Zustellungen gelten als Endgültig fehlgeschlagen. Nach dem Planwechsel senden aktive Endpunkte wieder, ohne dass du sie neu anlegen musst.

Planlimits

Plan	API, ICS und Webhooks
Free	nein
Solo	nein
Studio	ja
Business	ja

Die Anzahl der Endpunkte je Workspace ist nicht begrenzt.

Ergebnis

Der Endpunkt steht in der Tabelle mit Status Aktiv.
Eine abonnierte Änderung erzeugt ein Event. Letztes Event zeigt Zugestellt, solange der Empfänger mit einem Erfolgsstatus antwortet.
Zustellungen listet die einzelnen Versuche. Testevent senden kommt als ping beim Empfänger an.
Das Signatur-Secret liegt nur im Zielsystem, nicht erneut im Dashboard.

Wenn etwas schiefgeht

Beobachtung	Ursache	Nächster Schritt
Keine Berechtigung für Integrationen	Rolle Trainer:in	Owner oder Admin bitten
Nicht in diesem Plan enthalten.	Free oder Solo	Studio oder Business wählen
Der Webhook konnte nicht erstellt werden.	URL verstößt gegen eine Regel	HTTPS, Hostname und DNS-Auflösung prüfen; siehe Schritt 2
Buchung ohne Event	Endpunkt war Deaktiviert, Plan gesperrt oder Typ nicht abonniert	Auslöser in der Event-Referenz prüfen; Buchungen per REST-API nachladen
Endgültig fehlgeschlagen	Empfänger antwortet nicht mit `2xx`, Timeout, Weiterleitung oder TLS-Fehler	URL, Zertifikat und Antwortzeit prüfen; Erneut senden in Zustellungen
Versuch {n}	Zustellung läuft noch	Warten; dieselbe `x-orbinaut-event-id` nicht doppelt verbuchen
Event kommt doppelt an	Timeout oder Neustart nach erfolgreicher Verarbeitung	Anhand von `x-orbinaut-event-id` deduplizieren
Signatur ungültig nach Rotation	Altes Secret im Empfänger	Neues Secret einsetzen
Signatur ungültig ohne Rotation	Body vor der Prüfung verändert, etwa durch JSON-Parsing	Signatur über die unveränderten Bytes berechnen
Vom Plan blockiert	Plan ohne Webhooks oder Abonnement nicht aktiv	Plan wechseln oder Zahlung klären; siehe Plan-Sperre