Webhooks -- Konfigurationsanleitung (Backend)

Voraussetzungen

• Das Modul Webhooks muss für den Client aktiviert sein (Modulverwaltung)

• Die Konfiguration erfolgt unter: Add-Ons > Webhooks

Webhook für einen Shop aktivieren

1. Navigiere zu Add-Ons > Webhooks

2. Wähle einen Shop aus dem Dropdown

3. Setze Webhooks aktiv auf Ja

4. Klicke Speichern

Endpunkt hinzufügen

1. Klicke auf Endpunkt hinzufügen (maximal 10 pro Shop)

2. Fülle die Felder aus:

Pflichtfelder

Optionale Felder

Detailgrad (Payload Level)

Zusatzinformationen auswählen (nur bei Detailgrad „Vollständig")

Sowohl an der Bestellung als auch an jeder Bestellposition können zahlreiche Zusatzinformationen hinterlegt sein -- viele davon sind rein intern (z.B. Zahlungsdaten, Server- und Dateipfade oder interne Verarbeitungskennungen) oder personenbezogen (z.B. Kundendaten auf Bestellebene). Damit keine internen oder personenbezogenen Daten ungewollt nach außen gelangen, werden nur die von dir ausdrücklich ausgewählten Felder mitgesendet. Ist nichts ausgewählt, enthält die Payload keine Zusatzinformationen.

Felder, die du selbst im Backend pflegst -- etwa eine eigene interne Artikelbezeichnung, eine SAP-Nummer oder ein Lagerort -- stehen dir dagegen zur Auswahl zur Verfügung, auch wenn sie auf den ersten Blick intern wirken.

Die Auswahl erfolgt in zwei getrennten Bereichen: Bestellebene (Felder, die zur ganzen Bestellung gehören) und Positionsebene (Felder je Artikel/Position). Beide werden unabhängig voneinander gepflegt -- ein Feld, das du auf der Bestellebene auswählst, wird nicht automatisch auf der Positionsebene gesendet und umgekehrt.

So wählst du die Felder aus:

1. Setze den Detailgrad auf Vollständig -- daraufhin erscheinen die beiden Bereiche Bestellebene und Positionsebene

2. Bei einem neuen Endpunkt ist die Positionsebene bereits mit einigen technischen Standardfeldern (Liefer- und Versandinformationen wie Lieferzeit, Lieferdatum, Sendungsverfolgung) vorausgefüllt. Du kannst sie übernehmen, ergänzen oder entfernen. Die Bestellebene startet leer. Artikelspezifische Felder wie Material oder Format sind bewusst nicht vorausgefüllt -- sie heißen je Shop unterschiedlich und werden über den Picker hinzugefügt

3. Klicke im jeweiligen Bereich auf Feld hinzufügen, um Felder für diese Ebene auszuwählen. Es öffnet sich eine Liste der auf dieser Ebene tatsächlich in deinem Shop verwendeten Feldnamen -- jeweils mit einem Beispielwert, damit erkennbar ist, was sich dahinter verbirgt

4. Nutze das Suchfeld, um die Liste einzugrenzen, oder trage über Eigenes Feld hinzufügen einen Feldnamen von Hand ein

5. Mit Alle wählen übernimmst du alle aktuell in deinem Shop verfügbaren Felder dieser Ebene auf einmal. Wichtig: Das ist eine Momentaufnahme -- Felder, die später neu in deinem Shop auftauchen, werden nicht automatisch ergänzt, sondern müssen bewusst hinzugefügt werden

6. Mit Leeren entfernst du alle ausgewählten Felder der Ebene auf einmal, einzelne Felder entfernst du über das × an der jeweiligen Markierung

7. Klicke Speichern

Nicht sendbare Felder: Bestimmte interne Felder sind aus Sicherheitsgründen dauerhaft gesperrt und können nicht ausgewählt werden -- sie erscheinen weder in der Auswahlliste, noch werden sie gesendet, selbst wenn sie von Hand eingetragen werden. Beim Speichern wird ein solcher Eintrag mit einer Fehlermeldung abgewiesen.

Authentifizierung

Die HMAC-Signatur wird immer mitgesendet, unabhängig von der gewählten Authentifizierung. Zugangsdaten werden verschlüsselt in der Datenbank gespeichert.

Events auswählen

Events sind nach Kategorien gruppiert:

• Bestellungen -- order.created

• Bestellpositionen -- order.line_item.created

• Entwurfsbestellungen -- draft_order.created

• Positionsfreigaben -- approval.line_item.requested, approval.line_item.step_approved, approval.line_item.step_rejected, approval.line_item.step_reverted, approval.line_item.completed, approval.line_item.reset, approval.line_item.print_data_changed, approval.line_item.options_changed, approval.line_item.comment_added, approval.line_item.correction_requested, approval.line_item.approver_changed -- die Freigabe-Anforderung (requested) wird für alle positionsbezogenen Freigaben ausgelöst, die übrigen Ereignisse derzeit nur vom lokalen Bestellworkflow (Hinweis steht direkt unter dem Gruppen-Titel). Wenn das Eskalationsstufen-Add-On aktiviert ist, erscheinen zusätzlich approval.line_item.escalated und approval.line_item.reminder_sent in der Auswahl; mit dem Artikelwechsel-Add-On kommt approval.line_item.article_changed hinzu und (mit dem Workflow-Auswahl-Add-On) approval.line_item.workflow_changed; mit dem Add-On „Zuständige Person im Freigabeportal" erscheint approval.line_item.assignee_changed

• Benachrichtigungen -- notification.webhook_disabled

Jede Gruppe hat eine Wildcard-Checkbox (z.B. order.*), die alle Events der Gruppe abonniert -- auch zukünftige Events die später hinzugefügt werden.

Events mit einem roten \* sind noch nicht vollständig implementiert und werden nur in bestimmten Szenarien ausgelöst. Dazu gehören aktuell:

• order.cancelled, order.packed, order.shipped

• order.line_item.shipped, order.line_item.cancelled

Endpunkt testen (Ping)

1. Klicke auf das Papierflieger-Symbol am Endpunkt

2. Es wird ein Test-Ping mit Dummy-Daten gesendet

3. Das Ergebnis zeigt HTTP-Status, Antwortzeit und ggf. Fehlermeldung

Der Test-Ping sendet das Event webhook.test mit Beispieldaten. Er prüft ob die URL erreichbar ist und die Authentifizierung funktioniert.

Event manuell auslösen (Test Fire)

Im Bereich Testen kann ein beliebiges Event mit einer echten Bestellung ausgelöst werden:

1. Wähle ein Event aus dem Dropdown (z.B. order.created)

2. Gib eine Bestell-ID ein (die im System existiert)

3. Bei LineItem-Events: Gib zusätzlich eine Bestellpositions-ID ein

4. Klicke Event auslösen

Das Event durchläuft den gesamten Webhook-Flow (Payload laden, Transformer anwenden, HTTP-Versand via Queue). Die Payload wird mit "_test": true markiert, damit das Zielsystem erkennt, dass es ein manueller Testaufruf ist.

Freigabe-Events (approval.line_item.*) stehen im Test-Dropdown bewusst nicht zur Verfügung: Ein aussagekräftiger Testinhalt würde eine Position mitten in einem laufenden Freigabe-Workflow voraussetzen, und künstlich erzeugte Freigabedaten könnten im Zielsystem als echte Daten interpretiert werden. Zum Testen dieser Events einen echten Freigabe-Durchlauf mit einer Testbestellung durchführen und die Zustellung im Empfänger-Testprotokoll prüfen.

Das Ergebnis ist anschließend in den Delivery Logs sichtbar.

Eingebauter Test-Empfänger

Für Tests ohne externes Zielsystem gibt es einen eingebauten Empfänger:

1. Im Bereich Testen wird rechts die Test-Empfänger-URL angezeigt

2. Kopiere diese URL und trage sie als Endpunkt-URL ein

3. Webhooks die an diese URL gesendet werden, erscheinen direkt im Panel

4. Jeder empfangene Webhook zeigt Headers und Body (aufklappbar)

5. Logs können per Refresh-Button aktualisiert und per Papierkorb gelöscht werden

Der Test-Empfänger verifiziert die HMAC-Signatur -- nur Webhooks mit gültigem Secret werden gespeichert.

Secret anzeigen und regenerieren

1. Klicke auf das Schlüssel-Symbol am Endpunkt

2. Das Secret wird angezeigt (64 Zeichen, verschlüsselt gespeichert)

3. Über Regenerate Secret kann ein neues Secret generiert werden

Achtung: Nach dem Regenerieren funktioniert das alte Secret nicht mehr für die Signaturprüfung. Das Zielsystem muss mit dem neuen Secret aktualisiert werden.

Zustellungsprotokolle einsehen

1. Klicke auf das Listen-Symbol am Endpunkt

2. Die letzten Zustellversuche werden angezeigt mit:

   • Event-Name

   • Status (success, failed, retrying, disabled_by_circuit_breaker)

   • HTTP-Statuscode der Antwort

   • Dauer in Millisekunden

   • Anzahl Versuche

   • Zeitstempel

Payloads werden komprimiert gespeichert und bei erfolgreicher Zustellung automatisch gelöscht um Speicher zu sparen.

Circuit Breaker

Wenn ein Endpunkt 10 aufeinanderfolgende Fehler hat, wird er automatisch deaktiviert. Der Endpunkt wird mit dem Status "Circuit Breaker" in Gelb angezeigt.

Um den Endpunkt wieder zu aktivieren:

1. Behebe das Problem im Zielsystem

2. Bearbeite den Endpunkt und setze Aktiv auf Ja

3. Speichere -- der Fehlerzähler und der Deaktivierungs-Status werden automatisch zurückgesetzt

Log-Bereinigung

Alte Zustellungsprotokolle werden automatisiert durch einen geplanten Cronjob entfernt. Die Aufbewahrungsdauer kann bei Bedarf vom Hosting-Team angepasst werden.

Endpunkt löschen

1. Klicke auf das Papierkorb-Symbol am Endpunkt

2. Bestätige die Löschung

Alle zugehörigen Zustellungsprotokolle werden ebenfalls gelöscht.

Häufige Fragen

Antworten auf häufige Fragen findest du auf der separaten Seite Webhooks -- FAQ.