Webhooks verstehen

Webhooks informieren externe Systeme automatisch über Ereignisse in der tebio Plattform.

Während die REST API aktiv von einem externen System aufgerufen wird, sendet tebio bei einem relevanten Ereignis eine Nachricht an eine vorkonfigurierte Ziel-URL.

Webhooks sind besonders wichtig für Integrationen, bei denen externe Systeme zeitnah auf Änderungen in tebio reagieren sollen, zum Beispiel bei neuen Subscriptions, erstellten Rechnungen, erfolgreichen Zahlungen oder fehlgeschlagenen Zahlungseinzügen.

Grundprinzip

Ein Webhook ist ein HTTP POST Request, den tebio an eine von Ihnen konfigurierte Ziel-URL sendet, sobald ein bestimmtes Ereignis eintritt.

Beispiel:

1. Eine Zahlung für eine Subscription wird fällig.
2. tebio verarbeitet die Zahlung über die konfigurierte Zahlungsmethode.
3. Sobald sich der Zahlungsstatus ändert, erzeugt tebio ein Ereignis.
4. tebio sendet dieses Ereignis als Webhook an Ihre konfigurierte Ziel-URL.
5. Ihr externes System empfängt den Webhook und startet einen Folgeprozess, zum Beispiel Provisioning, CRM-Update oder Statusabgleich.

Dadurch muss Ihr System nicht dauerhaft per API nach Änderungen fragen. Stattdessen wird es automatisch informiert, wenn ein relevantes Ereignis eintritt.

Warum Webhooks wichtig sind

Viele Prozesse im Subscription Management und Billing laufen asynchron ab.

Ein API-Aufruf kann zum Beispiel eine Bestellung auslösen. Die Antwort auf diesen API-Aufruf bestätigt jedoch nicht zwingend, dass alle Folgeprozesse bereits abgeschlossen sind.

Folgeprozesse können zeitversetzt stattfinden, zum Beispiel:

• Zahlung wird verarbeitet
• Rechnung oder Quittung wird erzeugt
• Dokument wird erstellt
• Nachricht wird versendet
• Subscription wird aktiviert oder geändert
• externer Zahlungsanbieter meldet einen neuen Status
• SEPA-Lastschrift wird später bestätigt oder abgelehnt

Webhooks helfen dabei, diese asynchronen Statusänderungen zuverlässig an externe Systeme zu übermitteln.

Typische Anwendungsfälle

Webhooks werden häufig eingesetzt, um externe Systeme mit tebio zu synchronisieren oder Folgeprozesse auszulösen.

Typische Anwendungsfälle sind:

• Provisioning starten, wenn eine Subscription erstellt wurde
• Zugang in einer SaaS-Anwendung freischalten
• CRM-System aktualisieren, wenn ein Kunde erstellt oder geändert wurde
• ERP-System informieren, wenn eine Rechnung erstellt wurde
• Zahlungsausfall in einem externen System markieren
• Dokumente im eigenen Kundenportal anzeigen
• Supportprozess starten, wenn ein Helpdesk-Ticket erstellt wurde
• Reporting oder Data Warehouse aktualisieren
• Kampagnen- oder Automatisierungsprozesse überwachen, sofern das Modul verfügbar ist

API und Webhooks im Zusammenspiel

Die API und Webhooks erfüllen unterschiedliche Aufgaben.

Mechanismus	Zweck
REST API	Externes System ruft tebio aktiv auf, um Daten zu erstellen, zu ändern oder abzurufen
Webhook	tebio informiert ein externes System automatisch über ein Ereignis

Ein typisches Integrationsmuster sieht so aus:

1. Ein externes System löst über die API eine Bestellung aus.
2. tebio verarbeitet die Bestellung und startet Folgeprozesse.
3. tebio sendet Webhook-Ereignisse zu relevanten Statusänderungen.
4. Das externe System ruft bei Bedarf weitere Details über die API ab.
5. Das externe System aktualisiert eigene Daten oder startet weitere Prozesse.

Dieses Muster ist robuster als reines Polling, weil externe Systeme nicht ständig nach Änderungen fragen müssen.

Aufbau eines Webhook-Events

Ein Webhook enthält Informationen zum ausgelösten Ereignis und zur betroffenen Ressource.

Typische Bestandteile eines Webhook-Payloads können sein:

Bestandteil	Bedeutung
Event-ID	eindeutige technische Kennung des Ereignisses
Event-Typ	Art des Ereignisses, zum Beispiel Subscription erstellt oder Zahlung fehlgeschlagen
Zeitstempel	Zeitpunkt, zu dem das Ereignis aufgetreten ist
Ressourcentyp	betroffene Ressource, zum Beispiel Customer, Subscription, Invoice oder Payment
Ressourcen-ID	technische Kennung der betroffenen Ressource
Payload	weitere Ereignis- oder Ressourcendaten, sofern vom Ereignistyp bereitgestellt

Die genaue Struktur des Payloads hängt vom jeweiligen Ereignistyp ab und ist in der API-Referenz beschrieben.

Webhooks konfigurieren

Webhooks werden im tebio Business-Portal eingerichtet.

Für die Konfiguration benötigen Sie in der Regel:

• Ziel-URL Ihres Systems
• Auswahl der Ereignisse, die gesendet werden sollen
• Umgebung, zum Beispiel Playground oder Live
• gegebenenfalls ein Webhook Secret zur Signaturprüfung

Die Ziel-URL muss von tebio erreichbar sein und sollte HTTPS verwenden.

Es können mehrere Webhook-Endpunkte konfiguriert werden. Dadurch können unterschiedliche Systeme nur die Ereignisse erhalten, die sie tatsächlich benötigen.

Beispiele:

• CRM-System empfängt Customer-Ereignisse
• ERP-System empfängt Invoice- und Payment-Ereignisse
• Provisioning-System empfängt Subscription-Ereignisse
• Supportsystem empfängt Helpdesk-Ereignisse

Ereignisse gezielt auswählen

Nicht jedes externe System muss alle Ereignisse erhalten.

Wählen Sie nur die Ereignisse aus, die für den jeweiligen Integrationsfall erforderlich sind.

Das reduziert:

• Netzwerklast
• Verarbeitungsaufwand
• Fehlerquellen
• unnötige Kopplung zwischen Systemen

Beispiel:

Ein ERP-System benötigt möglicherweise Rechnungs- und Zahlungsereignisse, aber keine Helpdesk-Ereignisse.

Ein Provisioning-System benötigt möglicherweise Subscription-Ereignisse, aber keine Rechnungsvorlagen- oder Kommunikationsereignisse.

Webhook-Verarbeitung

Ein empfangender Webhook-Endpunkt sollte möglichst einfach und robust aufgebaut sein.

Empfohlenes Verarbeitungsmuster:

1. Webhook empfangen
2. Herkunft und Signatur prüfen
3. Event-ID auf bereits verarbeitete Ereignisse prüfen
4. Webhook schnell mit HTTP 2xx bestätigen
5. Ereignis intern in eine Queue oder Verarbeitungstabelle schreiben
6. eigentliche Geschäftslogik asynchron verarbeiten
7. bei Bedarf Details über die API abrufen

So vermeiden Sie, dass lange interne Prozesse die Webhook-Zustellung blockieren.

Schnelle Antwort mit HTTP 2xx

Ihr Webhook-Endpunkt sollte Webhook-Requests schnell mit einem erfolgreichen HTTP-Statuscode beantworten.

Typische erfolgreiche Antworten sind:

• 200 OK
• 202 Accepted

Komplexe Prozesse sollten nicht direkt innerhalb des Webhook-Requests ausgeführt werden.

Beispiele für Prozesse, die besser asynchron verarbeitet werden:

• interne Datenbankabgleiche
• Provisioning
• ERP-Synchronisation
• Versand eigener Nachrichten
• Generierung eigener Dokumente
• umfangreiche API-Nachfragen

Wenn tebio keine rechtzeitige erfolgreiche Antwort erhält, kann die Zustellung als fehlgeschlagen gelten und erneut versucht werden.

Idempotenz sicherstellen

Webhook-Ereignisse können mehrfach zugestellt werden.

Das kann zum Beispiel passieren, wenn:

• die Netzwerkverbindung unterbrochen wird
• Ihr System zu spät antwortet
• ein Retry ausgelöst wird
• der ursprüngliche Request verarbeitet wurde, aber die Antwort nicht bei tebio angekommen ist

Ihr System muss deshalb idempotent arbeiten.

Das bedeutet: Die mehrfache Verarbeitung desselben Ereignisses darf nicht zu fehlerhaften Zuständen führen.

Empfehlung:

• Speichern Sie empfangene Event-IDs.
• Prüfen Sie vor der Verarbeitung, ob die Event-ID bereits verarbeitet wurde.
• Verarbeiten Sie bekannte Event-IDs nicht erneut.
• Gestalten Sie Folgeprozesse so, dass Wiederholungen keine doppelten Buchungen, Freischaltungen oder Statuswechsel auslösen.

Sicherheit und Authentizität prüfen

Webhook-URLs sind in der Regel öffentlich erreichbar. Deshalb sollte Ihr System prüfen, ob eingehende Requests tatsächlich von tebio stammen.

Je nach Konfiguration kann tebio Webhooks mit einer Signatur oder einem Secret absichern.

Empfehlungen:

• Verwenden Sie HTTPS.
• Prüfen Sie die Webhook-Signatur, sofern vorhanden.
• Speichern Sie Webhook Secrets sicher.
• Akzeptieren Sie nur erwartete HTTP-Methoden.
• Verarbeiten Sie nur bekannte Ereignistypen.
• Protokollieren Sie abgelehnte Requests.
• Veröffentlichen Sie keine Webhook Secrets im Frontend-Code.

Die genaue technische Umsetzung der Signaturprüfung ist in der API-Referenz beschrieben.

Retries und Fehlerfälle

Wenn Ihr Webhook-Endpunkt nicht erreichbar ist oder mit einem Fehlerstatus antwortet, kann tebio eine erneute Zustellung versuchen.

Typische Fehlerfälle sind:

• Zielsystem ist nicht erreichbar
• Timeout
• HTTP 5xx
• ungültige Antwort
• temporäre Wartung
• Netzwerkfehler

Ihr System sollte so gebaut sein, dass Wiederholungen verarbeitet werden können.

Wichtig:

• Retries können dazu führen, dass dasselbe Ereignis mehrfach ankommt.
• Die Reihenfolge von Ereignissen kann nicht in jedem Integrationsfall garantiert werden.
• Ein späteres Ereignis kann unter Umständen vor einem früheren Ereignis verarbeitet werden.
• Der aktuelle Zustand sollte bei Bedarf über die API verifiziert werden.

Reihenfolge und aktueller Zustand

Verlassen Sie sich bei kritischen Prozessen nicht ausschließlich auf die Reihenfolge einzelner Webhooks.

Wenn der aktuelle Zustand wichtig ist, sollte Ihr System nach Empfang eines Webhooks die betroffene Ressource über die API abrufen.

Beispiel:

Ein Webhook meldet eine geänderte Subscription. Ihr System ruft anschließend die Subscription über die API ab und verarbeitet den aktuellen Status.

Dieses Muster ist besonders hilfreich, wenn mehrere Ereignisse kurz hintereinander auftreten oder ein externes System zeitweise nicht erreichbar war.

Monitoring und Logging

Webhook-Verarbeitung sollte überwacht werden.

Empfehlungen:

• eingehende Webhooks protokollieren
• Event-ID, Event-Typ und Zeitstempel speichern
• HTTP-Antwortstatus protokollieren
• Verarbeitungsstatus intern speichern
• fehlgeschlagene Verarbeitungen sichtbar machen
• manuelle Wiederholung oder Klärung ermöglichen
• Alarme für dauerhaft fehlschlagende Webhooks einrichten

So können technische Teams nachvollziehen, ob Webhooks empfangen und korrekt verarbeitet wurden.

Playground und Live trennen

Webhooks sollten für Playground und Live getrennt konfiguriert werden.

Verwenden Sie für Tests keine Live-Endpunkte, die produktive Folgeprozesse auslösen.

Empfehlung:

Umgebung	Empfehlung
Playground	Test-Endpunkte, Testdaten, technische Validierung
Live	produktive Endpunkte, produktive Folgeprozesse, Monitoring

Auch Webhook Secrets und API-Schlüssel sollten pro Umgebung getrennt behandelt werden.

Typische Fehler vermeiden

Webhooks als vollständige Datenquelle behandeln

Ein Webhook sollte häufig als Ereignishinweis verstanden werden.

Wenn Ihr System vollständige Details benötigt, rufen Sie die betroffene Ressource zusätzlich über die API ab.

Zu viele Ereignisse abonnieren

Abonnieren Sie nur Ereignisse, die Ihr System tatsächlich benötigt.

Zu viele Ereignisse erhöhen Komplexität und Fehleranfälligkeit.

Keine Idempotenz implementieren

Mehrfachzustellungen müssen erwartet werden. Ohne Idempotenz können doppelte Freischaltungen, doppelte interne Buchungen oder falsche Statuswechsel entstehen.

Geschäftslogik direkt im Webhook-Request ausführen

Lange Prozesse können Timeouts verursachen.

Bestätigen Sie den Webhook schnell und verarbeiten Sie die Geschäftslogik asynchron.

Signaturprüfung weglassen

Webhook-Endpunkte sind öffentlich erreichbar. Prüfen Sie daher die Authentizität eingehender Requests, sofern Signaturmechanismen konfiguriert sind.

Reihenfolge ungeprüft voraussetzen

Verarbeiten Sie Webhooks so, dass Ihr System mit Wiederholungen, Verzögerungen und geänderter Reihenfolge umgehen kann.

API-Hinweis

Die technische Beschreibung der Webhook-Konfiguration, verfügbaren Ereignistypen, Payload-Strukturen, Signaturen, Retry-Regeln und Statuscodes finden Sie in der separaten API-Referenz.

Dieser Artikel erklärt das Konzept und die empfohlene Verarbeitung auf fachlicher und architektonischer Ebene.

Verwandte Themen

• Webhooks einrichten
• Events nachvollziehen
• Integration im Überblick
• Typischer API-Workflow
• Portal-Objekte und API-Ressourcen
• API-Referenz
• Playground
• Glossar