Webhooks in Shopware 6: was der Kern selbst regelt

Webhooks sind der unauffälligste Teil einer Integration. Sie funktionieren monatelang, und wenn sie ausfallen, fällt es niemandem auf — weil nichts passiert, statt dass etwas schiefgeht.

Shopware nimmt einem dabei mehr ab, als viele erwarten. Und es hört an einer Stelle auf, die man kennen sollte.

Was Shopware selbst regelt

Wiederholung mit festen Abständen

Schlägt eine Zustellung fehl, wiederholt Shopware sie. Die Abstände sind im Kern fest hinterlegt:

public const RETRY_DELAYS_IN_SECONDS = [5, 30, 300, 1800, 14400];

Die Berechnung greift auf den letzten Wert zurück, wenn der Zähler über die Liste hinausläuft — es bleibt also bei vier Stunden. Das ergibt eine Gesamtspanne von gut fünf Stunden, bevor die ersten fünf Versuche durch sind.

Praktische Folge: Eine Gegenstelle, die zwanzig Minuten offline ist, holt sich alles von selbst wieder. Eine, die drei Tage ausfällt, nicht — siehe unten.

Abschaltung nach zehn Fehlern

public const MAX_ERROR_COUNT = 10;

Erreicht der Fehlerzähler diesen Wert, wird der Webhook deaktiviert. Das ist sinnvoll — ein dauerhaft kaputtes Ziel soll nicht endlos angefragt werden — und es ist die gefährlichste Eigenschaft des ganzen Mechanismus.

Ein deaktivierter Webhook meldet sich nicht. Er sendet nichts, erzeugt keine Fehler und fällt in keiner Überwachung auf, die auf Fehler achtet. Der Ausfall zeigt sich als Abwesenheit.

Outbox statt Direktversand

Die Zustellung läuft nicht im Anfragekontext, sondern über eine Outbox mit eigener Speicherung, einer Sperre gegen gleichzeitige Verarbeitung und einem Ereignisprotokoll. Das entkoppelt den Shop von der Erreichbarkeit der Gegenstelle — eine langsame Gegenstelle bremst nicht den Bestellabschluss.

Was Shopware nicht regelt

Idempotenz. Eine Wiederholung nach einer Zeitüberschreitung kann eine bereits verarbeitete Nachricht erneut zustellen. Ihre Gegenstelle muss dieselbe Nachricht zweimal verkraften, ohne zweimal zu handeln.

Reihenfolge. Es gibt keine Zusage, dass Ereignisse in der Reihenfolge ankommen, in der sie entstanden sind. Wer auf Reihenfolge angewiesen ist, braucht eine eigene Sortierung — etwa über einen Zeitstempel oder eine Versionsnummer aus der Nutzlast.

Überwachung. Der Fehlerzähler steht in der Datenbank. Ihn zu beobachten ist Ihre Aufgabe.

Die Felder der Webhook-Entität

Was Shopware je Webhook speichert:

only_live_version ist die Einstellung, die in Redaktionsumgebungen den Unterschied macht: Ohne sie lösen auch Entwürfe und Vorschauversionen aus.

Eine Überwachung, die trägt

Drei Punkte, in dieser Reihenfolge:

1. error_count je aktiven Webhook regelmässig ablesen. Alles über null ist ein Hinweis, alles über fünf ein Alarm — dann bleiben nur noch fünf Versuche bis zur Abschaltung.
2. active überwachen. Ein Webhook, der von true auf false wechselt, ist ein Ereignis, das jemand sehen muss.
3. Auf der Gegenseite zählen. Wenn dort täglich rund 200 Zustellungen ankommen und es plötzlich null sind, ist das der schnellste Indikator — unabhängig davon, ob Shopware etwas meldet.

Punkt 3 ist der wichtigste, weil er die Fehlerklasse trifft, die sich sonst nicht meldet: Es passiert einfach nichts mehr.

Dasselbe Muster gilt ausserhalb von Shopware. Ein Automatisierungsszenario ohne Fehlerpfad bricht genauso still ab — Fehlerbehandlung in Make beschreibt, wie man das dort auffängt.

Wann ein Webhook das falsche Werkzeug ist

Wenn Sie den Zustand brauchen, nicht das Ereignis. Ein Webhook sagt „etwas ist passiert". Wer den vollständigen aktuellen Datensatz braucht, sollte ihn nach dem Signal über die API holen, statt sich auf die Nutzlast zu verlassen.

Wenn Zustellung garantiert sein muss. Nach zehn Fehlern ist Schluss. Für Vorgänge, bei denen kein Ereignis verloren gehen darf, braucht es eine eigene Warteschlange, die den Zustand hält, bis die Gegenstelle bestätigt.

Wenn die Gegenstelle langsam ist. Eine Zustellung, die regelmässig in eine Zeitüberschreitung läuft, erzeugt Wiederholungen, die den Zähler hochtreiben — bis zur Abschaltung. Die Gegenstelle sollte annehmen und quittieren, dann verarbeiten.

Wo das im Alltag auftaucht

Bei jeder Anbindung an ein Warenwirtschafts-, PIM- oder CRM-System. Wie wir solche Schnittstellen bauen und betreiben, steht auf App- und Plugin-Entwicklung.

Wer Ereignisse ohne eigene Entwicklung verarbeiten will, kommt schnell zum Flow Builder — und stösst dort auf eine Grenze, die in Flow Builder: Auslöser, Aktionen und Grenzen beschrieben ist.