Webhooks -- Funktionsweise

Was sind Webhooks?

Webhooks sind automatische HTTP-Benachrichtigungen, die der Shop an externe Systeme sendet, wenn bestimmte Ereignisse eintreten (z.B. eine neue Bestellung, eine Stornierung, ein Versand). Anstatt dass das externe System regelmäßig nachfragen muss ("Polling"), wird es in Echtzeit informiert.

Ablauf

wide760 Erfolg, Zähler zurückgesetzt, Payload aus Log gelöscht Antwort nicht 2xx? --> Retry mit exponential Backoff (bis zu 5 Versuche) 10 aufeinanderfolgende Fehler? --> Circuit Breaker deaktiviert den Endpunkt]]>

Verfügbare Events

Bestellungen (order)

Event	Beschreibung	Status
order.created	Bestellung wurde angelegt und freigegeben/bezahlt	Aktiv
order.cancelled	Bestellung wurde storniert	Teilweise*
order.packed	Bestellung wurde gepackt	Teilweise*
order.shipped	Bestellung wurde versendet	Teilweise*

Bestellpositionen (order.line_item)

Event	Beschreibung	Status
order.line_item.created	Position wurde freigegeben (direkt oder nach Freigabe-Workflow)	Aktiv
order.line_item.shipped	Position wurde versendet	Teilweise*
order.line_item.cancelled	Position wurde storniert	Teilweise*

Entwurfsbestellungen (draft_order)

Event	Beschreibung	Status
draft_order.created	Bestellung angelegt, wartet auf Zahlung oder Freigabe	Aktiv

Benachrichtigungen (notification)

Event	Beschreibung	Status
notification.webhook_disabled	Endpunkt durch Circuit Breaker deaktiviert	Aktiv

*Teilweise = Event ist implementiert und wird in bestimmten Code-Pfaden ausgelöst, aber noch nicht an allen relevanten Stellen im Legacy-Code abgedeckt.

Payload-Detailgrade

Jeder Endpunkt kann einen von zwei Detailgraden konfigurieren:

Level	Beschreibung	Anwendungsfall
Minimal	Nur IDs und Status	System lädt Daten selbst nach, minimaler Traffic
Standard	Kernfelder (Preise, Adressen, Artikel-IDs)	Standardintegration, ERP-Anbindung

Sicherheit

• HMAC-SHA256 Signatur: Jeder Request wird mit einem pro-Endpunkt-Secret signiert (Header X-Shop-Signature)

• HTTPS: Nur HTTPS-URLs sind erlaubt

• Authentifizierung: Optional konfigurierbar (Basic Auth, Bearer Token, Custom Header)

• Idempotency: Jeder Event-Versand hat einen eindeutigen Key -- doppelte Zustellung wird verhindert

• Verschlüsselung: Secret und Auth-Zugangsdaten werden verschlüsselt in der Datenbank gespeichert

• Client-Isolation: Alle Daten sind per client_id isoliert -- kein client-übergreifender Zugriff möglich

Zuverlässigkeit

• Retry: Bei Fehlern wird bis zu 5x wiederholt (nach 1min, 5min, 15min, 1h, 2h)

• Circuit Breaker: Nach 10 aufeinanderfolgenden Fehlern wird der Endpunkt automatisch deaktiviert

• Delivery Logs: Jeder Zustellversuch wird protokolliert (Event, Status, HTTP-Code, Dauer)

• Speicheroptimierung: Payloads werden komprimiert gespeichert und bei erfolgreicher Zustellung gelöscht

Limits

• Maximal 10 Endpunkte pro Shop

• Timeout pro Request: 30 Sekunden

• Wildcard-Subscriptions möglich (z.B. order.* für alle Bestell-Events)

Glossar

Begriff	Erklärung
Endpunkt	Eine konfigurierte Ziel-URL die Webhook-Events empfängt
Event	Ein Ereignis im Shop (z.B. order.created)
Payload	Die Daten die mit dem Event mitgesendet werden
Secret	Ein pro-Endpunkt generierter Schlüssel für die HMAC-Signatur (verschlüsselt gespeichert)
Circuit Breaker	Sicherheitsmechanismus der Endpunkte nach wiederholten Fehlern deaktiviert
Idempotency Key	Eindeutiger Schlüssel pro Event-Versand zur Vermeidung doppelter Verarbeitung
Detailgrad	Konfigurierbare Tiefe der mitgesendeten Daten (Minimal, Standard)