Idempotenz beschreibt in der Softwareentwicklung die Eigenschaft einer Operation, bei mehrfacher identischer Ausführung immer zum gleichen fachlichen Ergebnis zu führen. Vereinfacht gesagt bedeutet das: Wird dieselbe Anfrage versehentlich mehrfach verarbeitet, darf dadurch nicht mehrfach dieselbe Aktion entstehen.
Das ist besonders wichtig bei APIs, Webhooks, Bestellungen, Zahlungen und synchronisierten Geschäftsprozessen. Ohne Idempotenz könnte ein technischer Wiederholungsversuch beispielsweise dazu führen, dass eine Bestellung doppelt angelegt, eine Zahlung mehrfach ausgelöst oder ein Lagerbestand mehrfach reduziert wird.
Im E-Commerce ist Idempotenz deshalb ein wichtiger Bestandteil zuverlässiger Schnittstellenarchitekturen.
Wie funktioniert Idempotenz?
Ein einfaches Beispiel ist die Erstellung einer Bestellung.
Ein externes System sendet folgende Anfrage:
„Erstelle Bestellung 4711.“
Die Anfrage wird verarbeitet und die Bestellung angelegt. Durch ein Netzwerkproblem erhält das sendende System jedoch keine eindeutige Bestätigung und es sendet somit dieselbe Anfrage erneut.
Ohne Idempotenz könnte nun eine zweite Bestellung entstehen, mit Idempotenz erkennt das empfangende System:
„Diese Anfrage wurde bereits verarbeitet.“
Statt eine neue Bestellung anzulegen, wird das Ergebnis der ersten Verarbeitung zurückgegeben.
Das Ziel ist deshalb nicht zwingend, doppelte Requests zu verhindern. Entscheidend ist, doppelte Auswirkungen zu verhindern.
Was ist ein Idempotency Key?
Eine häufig verwendete Methode ist ein sogenannter Idempotency Key.
Dabei erzeugt der Absender für einen bestimmten Vorgang eine eindeutige Kennung.
Beispiel:
order-4711-create
Die Anfrage enthält diesen Schlüssel.
Beim ersten Request speichert das Zielsystem:
- Idempotency Key
- Zeitpunkt
- Ergebnis
- gegebenenfalls Statuscode
Wird später derselbe Schlüssel erneut gesendet, erkennt das System die Wiederholung und führt die eigentliche Aktion nicht erneut aus.
Ein typischer Ablauf lautet:
Request → Idempotency Key prüfen → bereits vorhanden? → vorhandenes Ergebnis zurückgeben
Ist der Schlüssel unbekannt, wird die Aktion ausgeführt und anschließend gespeichert.
Warum ist Idempotenz bei APIs wichtig?
Netzwerke sind grundsätzlich nicht vollständig fehlerfrei.
Eine API Anfrage kann:
- zu lange dauern
- unterbrochen werden
- mit einem Timeout enden
- erneut gesendet werden
- durch einen Retry Mechanismus wiederholt werden
Das Problem besteht darin, dass der Absender bei einem Timeout möglicherweise nicht weiß, ob die ursprüngliche Anfrage verarbeitet wurde.
Eine erneute Anfrage ist deshalb häufig notwendig.
Idempotenz sorgt dafür, dass solche Wiederholungsversuche sicher durchgeführt werden können.
Idempotenz bei Webhooks
Auch bei Webhooks ist Idempotenz besonders wichtig. Denn Webhook Systeme arbeiten häufig nach dem Prinzip:
Ereignis senden → Bestätigung erwarten → bei Fehler erneut senden
Kommt die Bestätigung nicht rechtzeitig zurück, kann der Webhook erneut ausgeliefert werden.
Ein Beispiel:
Shop → Webhook → ERP
Der Webhook meldet:
„Neue Bestellung 4711.“
Das ERP verarbeitet die Bestellung, kann die Bestätigung aber aufgrund eines Netzwerkfehlers nicht erfolgreich zurücksenden.
Der Webhook wird daraufhin erneut übertragen.
Das ERP sollte deshalb die Ereignis ID speichern und prüfen, ob das Ereignis bereits verarbeitet wurde.
Beispiel im E-Commerce
Ein Zahlungsdienstleister meldet:
Zahlung erfolgreich
Wird derselbe Webhook dreimal übertragen, darf das System nicht:
- dreimal den Status ändern
- dreimal eine Rechnung erzeugen
- dreimal eine Versandfreigabe auslösen
Stattdessen sollte bereits nach der ersten erfolgreichen Verarbeitung gespeichert werden:
Payment Event XYZ verarbeitet
Weitere identische Ereignisse können anschließend ignoriert beziehungsweise bestätigt werden.
Idempotenz bei Shopware und Schnittstellen
Bei Shopware Integrationen ist Idempotenz insbesondere bei folgenden Prozessen relevant:
- Bestellimport
- Kundenimport
- Zahlungsstatus
- Versandstatus
- Lagerbestandsänderungen
- ERP Synchronisation
- Webhooks
- Middleware Prozesse
Ein ERP sollte beispielsweise nicht bei jedem wiederholten Request eine neue Shopware Bestellung erzeugen.
Stattdessen kann mit einer eindeutigen externen Bestellnummer geprüft werden, ob die Bestellung bereits vorhanden ist.
Ein möglicher Ablauf:
- ERP übermittelt Bestellung
ERP-123456 - Middleware sucht nach dieser externen Referenz
- Bestellung existiert noch nicht
- Bestellung wird angelegt
- externe Referenz wird gespeichert
- identische Anfrage kommt erneut
- vorhandene Bestellung wird erkannt
- keine zweite Bestellung wird erzeugt
Idempotenz und HTTP Methoden
Einige HTTP Methoden sind bereits konzeptionell idempotent.
| Methode | Typische Eigenschaft |
|---|---|
| GET | idempotent |
| PUT | grundsätzlich idempotent |
| DELETE | grundsätzlich idempotent |
| POST | normalerweise nicht automatisch idempotent |
| PATCH | abhängig von der Implementierung |
Ein mehrfach ausgeführtes GET verändert normalerweise keine Daten.
Ein POST kann dagegen bei jeder Ausführung einen neuen Datensatz erzeugen. Deshalb werden Idempotency Keys besonders häufig bei POST Requests eingesetzt.
Die tatsächliche Sicherheit hängt jedoch immer von der konkreten Implementierung ab.
Idempotenz und Retry Mechanismen
Retry Mechanismen und Idempotenz gehören eng zusammen.
Ein Retry bedeutet, dass eine fehlgeschlagene oder nicht eindeutig bestätigte Anfrage erneut ausgeführt wird.
Typische Gründe sind:
- Netzwerkfehler
- Server Timeout
- temporärer API Fehler
- nicht erreichbares System
Ohne Idempotenz können automatische Wiederholungen gefährlich sein.
Mit Idempotenz können Systeme dagegen deutlich robuster aufgebaut werden.
Vorteile von Idempotenz
Idempotente Prozesse bieten mehrere wichtige Vorteile:
- Schutz vor doppelten Bestellungen
- Schutz vor mehrfachen Zahlungen
- sichere Retry Mechanismen
- stabilere Webhook Verarbeitung
- weniger Dateninkonsistenzen
- bessere Fehlerbehandlung
- höhere Zuverlässigkeit bei verteilten Systemen
Besonders bei automatisierten Geschäftsprozessen reduziert Idempotenz das Risiko schwer nachvollziehbarer Folgefehler.
Grenzen und Herausforderungen
Idempotenz muss bewusst entwickelt werden.
Typische Herausforderungen sind:
- eindeutige Schlüssel definieren
- bereits verarbeitete Ereignisse speichern
- Speicherfristen bestimmen
- parallele Requests behandeln
- Race Conditions verhindern
- Status konsistent halten
Besonders schwierig wird es, wenn zwei identische Requests nahezu gleichzeitig eintreffen.
Dann muss das System sicherstellen, dass nicht beide Prozesse gleichzeitig davon ausgehen, der Vorgang sei noch nicht vorhanden.
Hier helfen beispielsweise Datenbank Locks, Unique Constraints oder atomare Operationen.
Idempotenz und Datenbank Unique Constraints
Eine sehr zuverlässige zusätzliche Schutzmaßnahme sind eindeutige Datenbankfelder.
Beispielsweise kann die externe Bestellnummer eindeutig sein:
external_order_id = ERP-123456
Die Datenbank erlaubt diesen Wert nur einmal.
Selbst wenn zwei Prozesse gleichzeitig versuchen, dieselbe Bestellung anzulegen, verhindert die Datenbank einen doppelten Datensatz.
Idempotency Keys und Datenbank Constraints werden deshalb häufig kombiniert.
Best Practices
Eine robuste Implementierung sollte folgende Punkte berücksichtigen:
- eindeutige Idempotency Keys verwenden
- Schlüssel vor Verarbeitung prüfen
- Ergebnis der ersten Verarbeitung speichern
- doppelte Ereignisse protokollieren
- Retry Mechanismen definieren
- Datenbank Constraints verwenden
- parallele Requests berücksichtigen
- Event IDs bei Webhooks speichern
- Logs und Monitoring einsetzen
Besonders geschäftskritische Prozesse wie Zahlungen und Bestellungen sollten grundsätzlich idempotent aufgebaut werden.
Abgrenzung zu Duplikaterkennung
Idempotenz und Duplikaterkennung sind eng verwandt, aber nicht identisch.
Duplikaterkennung prüft, ob ähnliche oder identische Daten bereits vorhanden sind.
Idempotenz stellt sicher, dass dieselbe Operation mehrfach ausgeführt werden kann, ohne das fachliche Ergebnis mehrfach zu erzeugen.
Eine gute Schnittstellenarchitektur kann beide Konzepte kombinieren.
FAQ zu Idempotenz
Was bedeutet idempotent einfach erklärt?
Eine Operation ist idempotent, wenn sie mehrfach ausgeführt werden kann, ohne dass sich das Ergebnis nach der ersten erfolgreichen Ausführung erneut verändert.
Warum ist Idempotenz bei Webhooks wichtig?
Webhooks können mehrfach ausgeliefert werden. Idempotenz verhindert, dass dasselbe Ereignis mehrfach verarbeitet wird.
Braucht jede API einen Idempotency Key?
Nein. Besonders wichtig ist er bei Aktionen, die Daten erzeugen oder Geschäftsprozesse auslösen.
Ist ein GET Request idempotent?
GET Requests gelten grundsätzlich als idempotent, da sie Daten lesen und normalerweise keine Zustandsänderung verursachen sollen.
Was passiert ohne Idempotenz?
Es können doppelte Bestellungen, Zahlungen, Buchungen oder andere unerwünschte Mehrfachaktionen entstehen.
Weiterführende Wiki-Einträge
Passende Themen sind:
Passende CUTVERT-Leistungen
Passende Leistungen von CUTVERT sind insbesondere:
Idempotenz: Bedeutung, Funktionsweise und Einsatz bei APIs und Webhooks
