Webhooks -- FAQ
Add-On Webhooks · FAQ
Diese Seite: Häufige Fragen zu Webhooks
Verwandte Seiten: Webhooks -- Funktionsweise, Webhooks -- Konfigurationsanleitung, Webhooks -- Integrationsleitfaden, Webhooks -- Payload-Referenz
Themen-Tags: webhooks, hmac, retries, circuit-breaker, events, endpunkte
F: Wie viele Webhook-Endpunkte kann ich pro Shop anlegen?
Kurzantwort: Maximal 10 Endpunkte pro Shop.
Details: Pro Shop können bis zu 10 Webhook-Endpunkte konfiguriert werden. Wenn du denselben Event an mehrere Zielsysteme schicken willst (z.B. ERP und Lagerverwaltung), legst du dafür einfach mehrere Endpunkte an und abonnierst den gleichen Event auf jedem. Das Limit gilt unabhängig vom Detailgrad oder der Authentifizierung der einzelnen Endpunkte.
Voraussetzungen: Add-On Webhooks für den Shop aktiviert.
Verwandte Themen: Webhooks -- Konfigurationsanleitung, Webhooks -- Funktionsweise
F: Kann ich denselben Webhook-Event an mehrere Zielsysteme senden?
Kurzantwort: Ja -- lege pro Zielsystem einen eigenen Endpunkt an und abonniere den gleichen Event auf beiden.
Details: Wenn z.B. order.created sowohl an dein ERP als auch an deine Lagerverwaltung gehen soll, legst du zwei Endpunkte an und aktivierst auf beiden den Event order.created. Jeder Endpunkt bekommt seine eigene HMAC-Signatur und kann unabhängig konfiguriert werden -- eigener Detailgrad, eigene Authentifizierung, eigene Retry-Historie.
Voraussetzungen: Add-On Webhooks aktiv, mindestens zwei freie Endpunkt-Slots (max. 10 pro Shop).
Verwandte Themen: Webhooks -- Konfigurationsanleitung, Webhooks -- Integrationsleitfaden
F: Was passiert mit meinem Webhook, wenn das Zielsystem kurz nicht erreichbar ist?
Kurzantwort: Der Webhook wird automatisch bis zu 5x wiederholt -- nach 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde und 2 Stunden.
Details: Wenn der erste Zustellversuch fehlschlägt (Timeout, 5xx-Fehler, Connection refused), reiht das System den Webhook in eine Retry-Queue ein. Insgesamt gibt es 5 Wiederholungsversuche mit ansteigenden Abständen. Schlagen alle Versuche fehl, wird der Webhook als endgültig fehlgeschlagen markiert und im Zustellungsprotokoll mit Status failed hinterlegt. Nach 10 aufeinanderfolgenden Fehlern greift zusätzlich der Circuit Breaker und deaktiviert den Endpunkt komplett.
Voraussetzungen: Endpunkt aktiv und nicht durch Circuit Breaker deaktiviert.
Verwandte Themen: Webhooks -- Funktionsweise, Webhooks -- Konfigurationsanleitung
F: Mein Webhook kommt nicht beim Zielsystem an -- wo fange ich mit der Fehlersuche an?
Kurzantwort: Prüfe in dieser Reihenfolge: Endpunkt aktiv (nicht im Circuit Breaker), gewünschter Event abonniert, Test-Ping erfolgreich, danach das Zustellungsprotokoll für Detail-Fehler.
Details: Die häufigsten Ursachen lassen sich in wenigen Schritten eingrenzen. (1) Status-Prüfung im Backend: Steht der Endpunkt auf „Aktiv"? Wenn er gelb mit „Circuit Breaker" markiert ist, wurde er nach 10 aufeinanderfolgenden Fehlern automatisch deaktiviert -- erst Zielsystem reparieren, dann Endpunkt reaktivieren. (2) Event-Abo prüfen: Ist der gewünschte Event (z.B. order.created) auf dem Endpunkt angehakt? Ohne Abo kein Versand. (3) Test-Ping über das Papierflieger-Symbol senden -- klärt URL-Erreichbarkeit und Authentifizierung. (4) Zustellungsprotokoll am Endpunkt öffnen: dort stehen HTTP-Code und Fehlermeldung. Häufige Codes: 401/403 = Auth oder Signatur falsch; 404 = URL existiert nicht; 5xx = Fehler im Zielsystem; Timeout = Antwort dauerte länger als 30 Sekunden. (5) Über „Event auslösen" mit einer echten Bestell-ID einen kompletten Lauf testen, falls die ersten Schritte unauffällig sind.
Voraussetzungen: Add-On Webhooks aktiv, mindestens ein konfigurierter Endpunkt.
Verwandte Themen: Webhooks -- Konfigurationsanleitung, Webhooks -- Integrationsleitfaden
F: Was ist der Unterschied zwischen den Webhook-Events order.created und draft_order.created?
Kurzantwort: draft_order.created feuert, sobald eine Bestellung angelegt wird; order.created erst, wenn sie freigegeben und/oder bezahlt ist.
Details: Eine Bestellung durchläuft im System mehrere Zustände. Sobald der Kunde abschickt, wird draft_order.created ausgelöst -- zu diesem Zeitpunkt wartet die Bestellung ggf. noch auf Zahlung oder einen Freigabe-Workflow. Erst wenn beides erledigt ist, feuert order.created. Praktischer Hinweis: Wenn dein Zielsystem nur abgeschlossene Bestellungen verarbeiten soll, abonniere order.created. Wenn du auch Entwürfe sehen willst (z.B. für Vorab-Reservierungen im Lager), abonniere zusätzlich draft_order.created.
Voraussetzungen: Add-On Webhooks aktiv, jeweiliger Event abonniert.
Verwandte Themen: Webhooks -- Payload-Referenz, Webhooks -- Konfigurationsanleitung
F: Wann wird der Webhook-Event order.line_item.created ausgelöst?
Kurzantwort: Sobald eine Bestellposition freigegeben und produktionsbereit ist -- entweder direkt nach Bestelleingang oder nach erfolgreichem Freigabe-Workflow.
Details: Im Gegensatz zu order.created bezieht sich order.line_item.created auf einzelne Positionen einer Bestellung, nicht auf die Bestellung als Ganzes. Bei Bestellungen ohne Freigabe-Workflow feuert das Event direkt nach Bestelleingang für jede Position. Bei Bestellungen mit Freigabe-Workflow feuert es individuell pro Position, sobald diese freigegeben wurde. Das ist nützlich, wenn dein Lager- oder Produktionssystem positionsweise statt bestellweise arbeitet.
Voraussetzungen: Add-On Webhooks aktiv, Event order.line_item.created abonniert.
Verwandte Themen: Webhooks -- Payload-Referenz, Webhooks -- Konfigurationsanleitung
F: Werden Webhooks auch rückwirkend für alte Bestellungen gesendet?
Kurzantwort: Nein -- Webhooks senden ausschließlich Events, die nach der Konfiguration neu auftreten.
Details: Webhooks feuern erst ab dem Zeitpunkt, an dem der Endpunkt angelegt und aktiviert wurde. Bestellungen, Freigaben oder andere Ereignisse, die vorher passiert sind, lösen keine Webhooks aus. Wenn du historische Daten ins Zielsystem bringen willst, müssen diese einmalig per API oder Export übertragen werden -- Webhooks sind ausschließlich für die laufende Synchronisation gedacht. Für gezielte Tests mit echten alten Bestellungen kannst du allerdings die „Event auslösen"-Funktion im Test-Bereich nutzen.
Voraussetzungen: keine.
Verwandte Themen: Webhooks -- Konfigurationsanleitung, Webhooks -- Funktionsweise
F: Wie sicher werden meine Webhook-Zugangsdaten gespeichert?
Kurzantwort: Alle Secrets und Zugangsdaten werden verschlüsselt in der Datenbank abgelegt -- weder in Logs noch in Backup-Dumps im Klartext einsehbar.
Details: Sowohl das HMAC-Secret als auch die Auth-Zugangsdaten (Basic-Auth-Passwort, Bearer-Token, Custom-Header-Werte) werden vor dem Speichern verschlüsselt. Das HMAC-Secret kann jederzeit über das Schlüssel-Symbol am Endpunkt eingesehen oder neu generiert werden. Achtung beim Regenerieren: Das alte Secret wird sofort ungültig, das Zielsystem muss zeitnah mit dem neuen Secret aktualisiert werden, sonst schlagen alle Signaturprüfungen fehl.
Voraussetzungen: keine.
Verwandte Themen: Webhooks -- Konfigurationsanleitung, Webhooks -- Integrationsleitfaden
F: Was bedeutet der rote Stern bei manchen Webhook-Events?
Kurzantwort: Der Stern markiert Events, die noch nicht vollständig implementiert sind und nur in bestimmten Szenarien feuern.
Details: Events mit rotem Stern -- aktuell order.cancelled, order.packed, order.shipped, order.line_item.shipped, order.line_item.cancelled -- sind teilweise implementiert. Sie werden in einigen Code-Pfaden bereits ausgelöst, aber noch nicht an allen relevanten Stellen im System. Du kannst diese Events bereits abonnieren; die Abdeckung wird schrittweise erweitert. Wenn deine Integration zwingend lückenlose Coverage braucht, plane mit ergänzenden Polling-Mechanismen oder warte auf den Stern-Wegfall.
Voraussetzungen: keine.
Verwandte Themen: Webhooks -- Funktionsweise, Webhooks -- Konfigurationsanleitung