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)

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

• 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.

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 disabled_at werden automatisch zurückgesetzt

Log-Bereinigung

Alte Delivery Logs können per Artisan-Command gelöscht werden:

Löscht alle Logs die älter als 30 Tage sind.

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.

FAQ

Wie viele Endpunkte kann ich pro Shop anlegen?
Maximal 10.

Kann ich denselben Event an mehrere URLs senden?
Ja, lege mehrere Endpunkte an und abonniere den gleichen Event.

Was passiert wenn das Zielsystem kurz nicht erreichbar ist?
Der Webhook wird bis zu 5x wiederholt: nach 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde und 2 Stunden.

Was ist der Unterschied zwischen order.created und draft_order.created?
draft_order.created wird ausgelöst wenn eine Bestellung angelegt wird, aber noch auf Zahlung oder Freigabe wartet. order.created wird ausgelöst wenn die Bestellung vollständig freigegeben und/oder bezahlt ist.

Was bedeutet order.line_item.created?
Die Bestellposition wurde freigegeben und ist bereit -- entweder direkt nach der Bestellung oder nach erfolgreichem Freigabe-Workflow.

Werden Webhooks auch für historische Bestellungen gesendet?
Nein, nur für neue Ereignisse ab dem Zeitpunkt der Konfiguration.

Werden Zugangsdaten sicher gespeichert?
Ja, das Secret und die Auth-Zugangsdaten (Passwörter, Tokens) werden verschlüsselt in der Datenbank gespeichert.

Was bedeuten die Events mit \*?
Diese Events sind teilweise implementiert. Sie werden in bestimmten Code-Pfaden ausgelöst, aber noch nicht an allen relevanten Stellen im System. Die Abdeckung wird schrittweise erweitert.