So richten Sie Benachrichtigungen über den Abschluss von API-Bestellungen ein

Welche Ereignisse als Abschluss einer Bestellung gelten

Legen Sie zunächst fest, welcher Status in der API den tatsächlichen Abschluss einer Bestellung bedeutet. Bei verschiedenen Anbietern kann dies eine ausgeführte, gelieferte, stornierte, abgelehnte, zurückgegebene oder teilweise ausgeführte Bestellung sein. Binden Sie die Automatisierung nicht nur an das Wort „Erfolg“: Eine Bestellung kann mehrere Zwischenzustände durchlaufen und dann aufgrund eines Limits, einer Prüfung oder einer Stornierung stoppen.

Es müssen nicht nur positive Ergebnisse verarbeitet werden. Wenn der Dienst eine Benachrichtigung über einen Fehler, eine Stornierung, eine Rückgabe oder eine teilweise Ausführung sendet, sollte diese ebenfalls im internen System erfasst werden. Andernfalls bleibt die Bestellung im Panel, im CRM oder im Bot im Wartezustand, obwohl die weitere Ausführung bereits nicht mehr stattfinden wird.

Erstellen Sie eine Zuordnungstabelle der Status

Geben Sie den API-Status nicht unverarbeitet an die Oberfläche weiter. Die Bezeichnungen und die Logik des Anbieters können sich ändern, und ein und derselbe interne Status fasst manchmal mehrere externe zusammen. Speichern Sie den ursprünglichen Wert separat: Er ist nützlich für die Fehleranalyse und den Abgleich mit der Dokumentation.

• pending, created, queued — neue oder zur Verarbeitung wartende Bestellung.
• processing, in_progress, running — Bestellung wird ausgeführt.
• completed, delivered, success — ausgeführte Bestellung.
• partial, partially_completed — teilweise ausgeführte Bestellung.
• cancelled, rejected, failed — stornierte oder mit Fehler beendete Bestellung.
• refunded, returned — Bestellung erfordert eine Rückerstattung oder Korrektur.
• Unbekannter Status — ändert die Karte nicht automatisch und wird zur Prüfung weitergegeben.

Die obigen Bezeichnungen sind als Beispielschema angegeben. Die endgültige Tabelle muss anhand der Status der jeweiligen API erstellt werden. Der Nachteil des manuellen Mappings besteht darin, dass es nach einer Aktualisierung der API gepflegt werden muss: Ein neuer Status kann im Handler eintreffen, bevor eine Regel dafür existiert.

Wählen Sie Webhooks, API-Polling oder beide Schemata

Ein Webhook ist eine Anfrage des Dienstes an Ihre URL bei einer Statusänderung der Bestellung. Das API-Polling funktioniert umgekehrt: Ihr System fragt in Intervallen Informationen zur Bestellung ab. Für Benachrichtigungen über den Abschluss sind in der Regel Webhooks bequemer, weil die Aktualisierung ohne ständige Anfragen an die Methode zur Statusprüfung eintrifft.

• Webhooks eignen sich für eine schnelle Reaktion: Aktualisierung der Karte, Start des nächsten Schritts oder Senden einer Nachricht an den Verantwortlichen.
• Polling eignet sich, wenn der Anbieter keine Callback-Benachrichtigungen unterstützt oder der Server keine externen Anfragen annimmt.
• Ein kombiniertes Schema nutzt Webhooks als Hauptkanal und Polling zur Suche nach verpassten oder hängengebliebenen Bestellungen.

Der Nachteil des Pollings ist die Verzögerung und die zusätzliche Belastung der API. Der Nachteil von Webhooks ist, dass der Endpoint geschützt werden muss, Duplikate berücksichtigt werden müssen und man sich nicht auf die Reihenfolge der Ereigniszustellung verlassen darf.

Richten Sie einen Endpoint für den Empfang von Ereignissen ein

Für Benachrichtigungen ist eine öffentliche HTTPS-Adresse erforderlich, die vom API-Dienst aus erreichbar ist. In den Integrationseinstellungen werden in der Regel die URL des Handlers, das Signaturgeheimnis und die Liste der Ereignisse angegeben: Statusänderung, Abschluss, Stornierung, Fehler oder teilweise Ausführung.

Richten Sie eine separate Route nur für API-Ereignisse ein. So lassen sich Protokollierung, Zugriffsbeschränkung und Ratenlimits einfacher konfigurieren, und der Dienstverkehr wird nicht mit Website-Formularen vermischt. Verwenden Sie keine Adresse der Testumgebung für Produktionsbestellungen: Nach einer Aktualisierung der Umgebung sendet der Anbieter Ereignisse weiterhin an die gespeicherte URL.

Prüfen Sie vor dem Start die Anfragemethode und das Body-Format anhand der Dokumentation. Meistens ist es POST mit JSON, es kommen aber auch form-data, Query-Parameter oder ein eigenes Serialisierungsschema vor. Ein Parsing-Fehler muss im Protokoll erfasst werden, sonst ist es schwierig, einen fehlerhaften Payload von einem Anwendungsfehler zu unterscheiden.

Speichern Sie die Verknüpfung zwischen Bestellung und Ereignis

Speichern Sie beim Erstellen einer Bestellung über die API die vom Anbieter zurückgegebene Kennung. Daneben speichern Sie die interne Bestellnummer, die Art der Dienstleistung, den ursprünglichen Status, den Zeitpunkt der letzten Änderung und die ursprüngliche API-Antwort in sicherer Form. Ordnen Sie den eingehenden Webhook anhand der Anbieter-ID zu, nicht anhand des Links zum Kanal, des Namens der Dienstleistung oder des Kundennamens.

Wenn die API das Übermitteln einer externen Kennung beim Erstellen erlaubt, fügen Sie Ihre Bestellnummer in einem Feld wie external_id oder client_reference hinzu. Das erleichtert die Suche in den Logs und die Klärung strittiger Situationen. Machen Sie die externe Nummer jedoch nicht zum einzigen Schlüssel: Einige Anbieter geben sie nicht in jeder Benachrichtigung zurück.

Erstellen Sie keine neue Bestellung anhand einer unbekannten ID aus dem Webhook. Ein unbekanntes Ereignis muss im Protokoll gespeichert und separat geprüft werden. Das automatische Anlegen eines Datensatzes kann zu fehlerhaften Daten oder zur Verarbeitung einer gefälschten Anfrage führen.

Verwenden Sie eine verständliche Payload-Struktur

Die genauen Feldnamen hängen von der API ab. Das Folgende ist kein Vertrag eines bestimmten Dienstes, sondern ein Beispiel für ein JSON-Ereignis, an dem man sich bei der Entwicklung des internen Handlers orientieren kann. Wichtig sind die Ereignis-ID, die Bestell-ID beim Anbieter, der Status, der Änderungszeitpunkt und Daten zur Diagnose.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

Verwenden Sie die Anzahl der ausgeführten Einheiten nicht ohne Status als Abschlussmerkmal. Eine Bestellung kann teilweise ausgeführt sein, und die Zahl im Payload kann gerundet, mit Verzögerung aktualisiert oder gar nicht übermittelt worden sein. Der Nachteil der Speicherung des vollständigen Ereignis-Bodys besteht darin, dass er personenbezogene Daten oder interne Felder enthalten kann; daher müssen solche Einträge maskiert und in der Aufbewahrungsfrist begrenzt werden.

Prüfen Sie die Signatur anhand des ursprünglichen Anfrage-Bodys

Eine offene Handler-URL kann eine Anfrage nicht nur vom API-Dienst erhalten. Wenn der Anbieter eine Signatur, ein Geheimnis oder ein Token übermittelt, prüfen Sie diese vor der Änderung der Bestellung. Ein verbreitetes Schema ist HMAC-SHA256: Der Anbieter berechnet die Signatur aus den Bytes des Anfrage-Bodys und einem gemeinsamen Geheimnis und übermittelt das Ergebnis dann in einem HTTP-Header.

Das Berechnungsprinzip sieht so aus: Es wird der ursprüngliche Anfrage-Body genommen, beispielsweise die JSON-Bytes ohne Änderungen, und das Integrationsgeheimnis. Dann wird HMAC-SHA256 berechnet. Wenn das Ergebnis in hexadezimaler Form mit dem Wert des Headers übereinstimmt, wurde der Body nach der Signierung nicht verändert und die Anfrage wurde wahrscheinlich von einer Seite gesendet, die das Geheimnis kennt.

Bedingtes Beispiel: HMAC_SHA256(Geheimnis, raw_body) = Signatur aus dem Header X-Signature. Der Name des Headers, der Algorithmus und das Format des Ergebnisses dürfen nur aus der API-Dokumentation entnommen werden. Einige Dienste fügen der zu signierenden Zeichenkette einen Zeitstempel oder eine Ereignis-ID hinzu. In diesem Fall darf nicht nur der JSON-Body geprüft werden.

Ändern Sie das JSON nicht vor der Signaturprüfung

Die Signatur wird anhand der ursprünglichen Anfrage-Bytes geprüft, nicht anhand des JSON-Objekts, das die Anwendung bereits geparst und neu zusammengesetzt hat. Bei einer erneuten Serialisierung können sich die Reihenfolge der Felder, Leerzeichen, Zeichen-Escaping, Zeilenumbrüche oder die Kodierung ändern. Für einen Menschen bleibt das JSON dasselbe, aber die Bytefolge ändert sich, und der HMAC stimmt nicht mehr überein.

Um dies zu vermeiden, holen Sie sich zuerst den raw body als bytes oder buffer, speichern Sie ihn im Speicher, berechnen Sie die Signatur und parsen Sie das JSON erst nach erfolgreicher Prüfung. Wenden Sie auf den Body kein trim, keine Kodierungsumwandlung, keine Schlüsselsortierung und keine Formatierung an. Prüfen Sie in der Middleware des Frameworks, ob das JSON nicht automatisch vor dem Zugriff auf den ursprünglichen Body geparst wird.

Der Nachteil dieses Schemas ist, dass der Handler von der Reihenfolge der Middleware abhängig wird. Bei falscher Konfiguration sieht die Anwendung nur das umgewandelte Objekt, und legitime Benachrichtigungen werden abgelehnt.

Beispiel eines Handlers mit HMAC-Prüfung

Unten ein bedingtes Beispiel in Python. Es zeigt die Reihenfolge der Aktionen, keine fertige Integration: Header, Algorithmus, Signaturformat und Payload-Felder müssen durch die Werte aus der Anbieterdokumentation ersetzt werden.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Verwenden Sie für den Vergleich eine Funktion, die nicht beim ersten nicht übereinstimmenden Zeichen abbricht. Das verringert das Risiko eines Datenlecks über die Antwortzeit. Übermitteln Sie das Geheimnis nicht an den Client-Code, fügen Sie es nicht in die URL ein und schreiben Sie es nicht vollständig in die Logs.

Machen Sie die Ereignisverarbeitung idempotent

Der Anbieter kann dasselbe Ereignis mehrmals zustellen. Die Gründe sind üblich: Ihr Server hat zu lange geantwortet, die Verbindung wurde nach dem Speichern der Daten unterbrochen, der Endpoint hat vorübergehend einen Fehler zurückgegeben oder der Dienst hat eine erneute Zustellung nach seinen eigenen Regeln gestartet. Eine Wiederholung bedeutet nicht, dass die API eine neue Bestellung erstellt hat.

Idempotenz bedeutet, dass dasselbe Ereignis das Ergebnis nur einmal ändert. Wird diese Regel nicht berücksichtigt, sendet ein Duplikat erneut eine Nachricht an den Kunden, erstellt mehrere Aufgaben für den Manager, gewährt eine Entschädigung oder startet eine erneute Operation.

Am besten verwenden Sie die event_id aus dem Payload. Speichern Sie sie in einer separaten Tabelle oder einem Journal verarbeiteter Ereignisse mit einer eindeutigen Einschränkung. Wenn es keine separate ID gibt, bilden Sie den Schlüssel aus stabilen Feldern: ID der Anbieterbestellung, Ereignistyp, Status und Änderungszeitpunkt. Diese Variante ist schlechter: Bei ungenauen Zeitstempeln können verschiedene Ereignisse gleich aussehen.

Speichern Sie Ereignis und Status in einer Operation

Die Prüfung „Ist das Ereignis verarbeitet?“ und das Schreiben des Ergebnisses müssen atomar erfolgen. Andernfalls sehen zwei gleichzeitig eintreffende identische Anfragen beide das Fehlen des Eintrags und starten die Aktion zweimal. Eine praktikable Variante ist ein eindeutiger Index auf event_id und eine Datenbanktransaktion.

Die bedingte Fortsetzung des Handlers sieht so aus:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

Der Nachteil einer erfolgreichen Antwort für eine unbekannte Bestellung besteht darin, dass der Anbieter die Zustellung möglicherweise nicht wiederholt. Daher müssen unbekannte Ereignisse separat überwacht und schnell geklärt werden. Wenn die API-Dokumentation für solche Fälle einen anderen Antwortcode empfiehlt, folgen Sie dieser.

Berücksichtigen Sie die Verletzung der Ereignisreihenfolge

Webhooks kommen nicht immer streng nach dem Zeitpunkt der Statusänderung an. Zuerst kann ein Ereignis über den Abschluss eintreffen und danach eine verspätete Benachrichtigung über den Status „in Bearbeitung“. Wenn einfach der zuletzt empfangene Wert gespeichert wird, wird eine ausgeführte Bestellung wieder aktiv.

Legen Sie zulässige Übergänge fest. Beispielsweise darf ein Zwischenstatus einen finalen Status nicht überschreiben, und eine stornierte Bestellung wird nicht ohne separate Prüfung in eine ausgeführte überführt. Wenn die API eine Korrektur des finalen Status zulässt, speichern Sie den Grund, den ursprünglichen Wert und die Quelle der Änderung.

Wenn der Payload den Zeitpunkt der Bestelländerung enthält, vergleichen Sie genau diesen und nicht den Zeitpunkt des Webhook-Empfangs. Wenn die API eine solche Angabe nicht übermittelt, verwenden Sie Statusprioritäten und einen Abgleich über die Methode zum Abrufen der Bestellung. Der Nachteil von Prioritäten ist, dass sie die tatsächliche Reihenfolge nicht ersetzen, insbesondere wenn der Anbieter eine Rückgabe aus einem finalen Status erlaubt.

Bestätigen Sie die Zustellung schnell und lagern Sie Aktionen in eine Warteschlange aus

Führen Sie keine langen Operationen vor der Antwort an den Anbieter aus. Signaturprüfung, Bestellsuche, Ereignisspeicherung und Statusaktualisierung können in der Regel schnell abgeschlossen werden. Das Senden einer Nachricht, die Synchronisierung mit dem CRM, die Erstellung eines Berichts oder Anfragen an Drittsysteme sollten besser an eine Aufgabenwarteschlange übergeben werden.

Die funktionierende Reihenfolge ist folgende: Signatur prüfen, Ereignis und Statusänderung atomar speichern, eine erfolgreiche Antwort zurückgeben, dann sekundäre Aktionen ausführen. Wenn Sie vor dem Speichern antworten, gehen bei einem Ausfall Daten verloren. Wenn Sie erst nach dem langen Senden einer Benachrichtigung antworten, kann der Anbieter die Zustellung als fehlgeschlagen betrachten und ein Duplikat senden.

Der Nachteil der Warteschlange ist, dass eine separate Komponente entsteht, die überwacht werden muss: Aufgabenfehler, Verzögerungen und erneute Ausführungen. Dafür blockiert ein Fehler in der Manager-Benachrichtigung nicht den Empfang von Bestellstatus.

Richten Sie Benachrichtigungen für das Team und den Kunden ein

Nach einer Statusänderung müssen nicht alle gleich benachrichtigt werden. Für den Manager sind in der Regel Stornierungen, Fehler, teilweise Ausführungen und Bestellungen wichtig, die sich lange nicht ändern. Für den Kunden reicht oft ein verständliches Endergebnis: Bestellung ausgeführt, storniert oder erfordert eine Klärung.

• Ausgeführte Bestellung — Aktualisierung im Kundenkonto oder eine kurze Nachricht an den Kunden.
• Ausführungsfehler — Benachrichtigung an den Verantwortlichen mit dem von der API übermittelten Grund.
• Teilweise Ausführung — Aufgabe zur Prüfung einer Korrektur, Rückerstattung oder der nächsten Aktion.
• Unbekannter Status — Eintrag im Protokoll und Nachricht an den technischen Spezialisten.
• Unbekannte Bestell-ID — separate Prüfung der Verknüpfung zwischen Ihrem System und dem Anbieter.

Senden Sie keine Nachricht bei jedem technischen Übergang. Der Feed wird schnell zu Rauschen, und ein wichtiges Problem bleibt unbemerkt. Eine interne Benachrichtigung sollte die Bestellnummer, die Dienstleistung, den aktuellen Status, die externe ID und einen Link zur Karte enthalten.

Führen Sie ein Protokoll und gleichen Sie nicht abgeschlossene Bestellungen ab

Logs werden benötigt, um zu verstehen, ob der Dienst ein Ereignis gesendet hat, welcher Body eingetroffen ist, warum die Signatur nicht durchgelaufen ist und an welcher Stelle die Verarbeitung gestoppt wurde. Speichern Sie den Empfangszeitpunkt, die Ereignis-ID, die Bestell-ID, den Ereignistyp, das Ergebnis der Signaturprüfung, den internen Status und den Antwortcode. Maskieren Sie Geheimnisse, Tokens und personenbezogene Daten.

Verfolgen Sie separat Zustellfehler, ungültige Signaturen, unbekannte Bestellungen, nicht unterstützte Status, Duplikate und Ereignisse, die aufgrund der Statusreihenfolge nicht angewendet werden können. Ein Anstieg solcher Einträge kann auf eine Änderung des API-Schemas, ein abgelaufenes Geheimnis, einen Routenfehler oder einen Fehler in der Handler-Logik hindeuten.

Gleichen Sie regelmäßig Bestellungen in Zwischenstatus über die Methode zum Abrufen der API-Daten ab. Diese Prüfung ersetzt keine Webhooks, hilft aber, ein verpasstes Ereignis, einen Warteschlangenfehler oder einen Fall zu erkennen, in dem sich der externe Status ohne korrekte Benachrichtigung geändert hat.