Webhook-Empfänger gestalten: Signaturprüfung, Duplikate und Reihenfolge

Webhook-Signaturprüfung, Replay-Fenster, schnelle 2xx-Antwort, Duplikatfilterung per Ereignis-ID und Ereignisse außer der Reihe: Bruchstellen aus der Praxis und Codebeispiele.
Technische Zusammenfassung
Technologie
Webhook, HMAC-SHA256, RFC 2104, PostgreSQL, Microsoft Graph change notifications
Thema
Eingehende Webhooks sicher, ohne Duplikate und in der richtigen Reihenfolge verarbeiten
Niveau
Mittel bis fortgeschritten
Voraussetzungen
  • Kenntnisse in HTTP und JSON
  • Grundlegendes SQL und eine serverseitige Sprache (Python, PHP usw.)
In diesem Beitrag8 Abschnitte

Meldet ein Zahlungsdienstleister, ein ERP, ein CRM oder ein Versanddienstleister ein Ereignis per Webhook, ist der Endpunkt, der die Anfrage annimmt, der fragilste Teil der Integration. Er muss gefälschte Anfragen ablehnen, dasselbe Ereignis nicht doppelt verarbeiten, die Daten durch in umgekehrter Reihenfolge eintreffende Ereignisse nicht beschädigen und das sendende System nicht warten lassen. Die meisten Webhook-Störungen in der Praxis entstehen, weil eine dieser vier Aufgaben übersprungen wird: Die Signatur wird über geparstes JSON berechnet, die Geschäftslogik läuft innerhalb der Anfrage, eine Duplikatprüfung fehlt.

Aufgaben des Webhook-Empfängers

In Unternehmens-Web- und Integrationsprojekten ist der Webhook-Empfänger ein offen im Internet stehender HTTP-Endpunkt, dessen Authentifizierung nicht auf einer Nutzersitzung, sondern auf einem gemeinsamen Geheimnis beruht. Ein korrekt aufgebauter Empfänger erledigt diese Aufgaben in dieser Reihenfolge:

  1. Er liest den Rohkörper (raw body) der Anfrage unverändert und wendet eine Größenbegrenzung an.
  2. Er prüft Signatur und Zeitstempel; schlägt das fehl, lehnt er ab, ohne zu verarbeiten.
  3. Er schreibt das Ereignis mit seiner eindeutigen ID in einen persistenten Eingang (Inbox); wurde die ID bereits gesehen, schreibt er es nicht erneut.
  4. Er antwortet dem Absender schnell mit 2xx.
  5. Er führt die eigentliche Geschäftslogik (Bestellstatus aktualisieren, ins ERP übertragen) in einem separaten Worker-Prozess aus.

Der Grund für diese Trennung ist einfach. Erhält der Absender die Antwort nicht innerhalb einer bestimmten Zeit, wertet er die Anfrage als fehlgeschlagen und sendet sie erneut. Läuft die Geschäftslogik innerhalb der Anfrage, bedeutet ein langsamer ERP-Aufruf sowohl einen Timeout als auch ein erneutes Eintreffen desselben Ereignisses. Ergebnis: Dieselbe Bestellung wird zweimal verarbeitet. Welche Daten per Webhook und welche per Queue oder Batch-Übertragung transportiert werden, behandelt der Leitfaden zu Integrationsmustern zwischen ERP und Web; hier betrachten wir nur den empfangenden Endpunkt.

HMAC-Signaturprüfung und Zeitstempelkontrolle

Bei der verbreiteten Methode wird mit einem Geheimnis, das Absender und Empfänger teilen, ein HMAC-SHA256-Hash des Anfragekörpers berechnet und in einem Header gesendet. Die HMAC-Struktur ist in RFC 2104 definiert. Anbieter unterscheiden sich beim Headernamen und beim signierten Inhalt:

Beispiel Signatur-Header Signierter Inhalt
GitHub X-Hub-Signature-256 (mit Präfix sha256=) Rohkörper
Stripe Stripe-Signature (Felder t= und v1=) Zeitstempel + Punkt + Rohkörper
Standard Webhooks webhook-signature Ereignis-ID + Zeitstempel + Rohkörper

Sendet Ihr eigenes System Webhooks an andere Systeme, wählen Sie ein Schema, das den Zeitstempel in die Signatur einbezieht; eine klare Beschreibung bietet die Spezifikation Standard Webhooks als guten Ausgangspunkt. Wird der Zeitstempel nicht signiert, kann eine abgefangene gültige Anfrage Tage später erneut gesendet werden (Replay-Angriff). Das folgende Python-Beispiel zeigt die Prüfung in einem Schema, das den Zeitstempel signiert; die Headernamen dienen nur als Beispiel.

import hmac, hashlib, time

TOLERANZ_S = 300  # akzeptierte Uhrzeitabweichung

def signatur_gueltig(roh_body: bytes, signatur: str, zeitstempel: str, geheimnis: bytes) -> bool:
    try:
        ts = int(zeitstempel)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - ts) > TOLERANZ_S:
        return False                      # ausserhalb des Replay-Fensters
    signiert = zeitstempel.encode() + b"." + roh_body
    erwartet = hmac.new(geheimnis, signiert, hashlib.sha256).hexdigest()
    return hmac.compare_digest(erwartet, signatur)   # Vergleich in konstanter Zeit

Drei Details in diesem Code brechen in der Praxis am häufigsten:

  • Der Rohkörper muss verwendet werden. Die meisten Web-Frameworks parsen JSON-Bodys automatisch. Ein geparster und neu serialisierter Body erzeugt wegen Unterschieden bei Leerzeichen und Feldreihenfolge nicht dieselben Bytes; die Signatur passt nicht. Führen Sie die Prüfung mit der Methode des Frameworks für den Zugriff auf den Rohkörper durch. Das ist der erste Prüfpunkt bei der Beschwerde „richtiges Geheimnis, falsche Signatur“.
  • Der Vergleich muss in konstanter Zeit erfolgen. == stoppt beim ersten abweichenden Zeichen und erzeugt einen Timing-Seitenkanal; verwenden Sie in Python hmac.compare_digest, in PHP hash_equals.
  • Die Serveruhr muss stimmen. Das Toleranzfenster setzt eine per NTP synchronisierte Uhr voraus. Weicht die Uhr einige Minuten ab, werden alle Anfragen abgelehnt. Prüfen Sie zuerst die Ausgabe von timedatectl.

Akzeptieren Sie beim Rotieren des Geheimnisses (Secret Rotation) für eine kurze Übergangszeit zwei Geheimnisse: Fügen Sie zuerst das neue Geheimnis beim Empfänger hinzu, ändern Sie es dann beim Absender, und entfernen Sie zuletzt das alte. Kehren Sie die Reihenfolge um, erhalten während des Wechsels eintreffende Ereignisse 401. Eine IP-Allowlist kann eine zusätzliche Schicht sein, ersetzt die Signaturprüfung aber nicht; die IP-Bereiche von Cloud-Anbietern ändern sich.

Schnelle Bestätigung, asynchrone Verarbeitung

Ist die Signatur gültig, schreibt der Empfänger das Ereignis in eine persistente Tabelle und antwortet sofort. Das persistente Schreiben muss vor der Antwort abgeschlossen sein. Ein Ereignis, das in eine In-Memory-Queue gelegt und mit 200 bestätigt wurde, geht verloren, wenn der Prozess neu startet. Und der Anbieter sendet es nicht noch einmal. Beispiel einer Inbox-Tabelle für PostgreSQL:

CREATE TABLE webhook_inbox (
  event_id     text        PRIMARY KEY,
  source       text        NOT NULL,
  event_type   text        NOT NULL,
  received_at  timestamptz NOT NULL DEFAULT now(),
  payload      jsonb       NOT NULL,
  status       text        NOT NULL DEFAULT 'pending',
  attempts     int         NOT NULL DEFAULT 0,
  last_error   text
);

INSERT INTO webhook_inbox (event_id, source, event_type, payload)
VALUES ($1, $2, $3, $4)
ON CONFLICT (event_id) DO NOTHING;

Wählen Sie die Antwortcodes bewusst. Liefern Sie bei ungültiger Signatur 401 oder 403, bei fehlerhaftem Body 400. Ist das Speichern erfolgreich oder existiert das Ereignis bereits, liefern Sie 200 oder 202. Kann nicht in die Datenbank geschrieben werden, ist 5xx richtig; der Absender versucht es erneut. Einen Fehler in der Geschäftslogik (etwa Artikel im ERP nicht gefunden) spiegeln Sie dagegen nicht mit 5xx an den Absender. Dieser Fehler behebt sich nicht durch Wiederholung; er belegt die Queue des Absenders unnötig und kann bei manchen Anbietern bis zur Deaktivierung des Endpunkts führen. Solche Fehler werden auf Worker-Seite über die Felder status und last_error behandelt.

Der Worker-Prozess nimmt Einträge mit pending; in PostgreSQL ist SELECT … FOR UPDATE SKIP LOCKED die verbreitete Methode, um zu verhindern, dass mehrere Worker denselben Eintrag nehmen. Nach einer bestimmten Zahl fehlgeschlagener Versuche wird der Eintrag in einen eigenen Status versetzt und landet zur manuellen Prüfung. Details der Wiederholungsrichtlinie beschreibt der Leitfaden zu API-Fehlerbehandlung und Retry.

Doppelte Ereignisse und idempotente Verarbeitung

Verbreitete Webhook-Anbieter arbeiten mit einem Zustellmodell „mindestens einmal“ (at-least-once); eine einmalige Zustellung garantieren sie nicht. Netzwerkunterbrechung, Timeout oder eine Antwort des Empfängers, die den Absender nicht erreicht, führen dazu, dass dasselbe Ereignis mehrfach eintrifft. Duplikate sind normal. Die Abwehr ist zweistufig:

  • Filterung per Ereignis-ID: Der Primärschlüssel event_id in der obigen Tabelle verhindert, dass dasselbe Ereignis ein zweites Mal geschrieben wird. Gibt es keine Ereignis-ID, kann ein Hash-Schlüssel aus Quelle, Ereignistyp, ID des Quelldatensatzes und Ereigniszeit verwendet werden. Das ist die zweite Wahl: Entstehen in derselben Sekunde tatsächlich zwei verschiedene Ereignisse, können sie kollidieren.
  • Die Operation selbst idempotent machen: Operationen der Form „Bestand soll 37 sein“ statt „Bestand um 5 verringern“ oder „diese Zahlung hinzufügen, falls die Zahlungs-ID nicht existiert“ statt „Zahlung hinzufügen“ ändern das Ergebnis bei Wiederholung nicht. Selbst wenn die Tabelle der Ereignis-IDs eines Tages bereinigt wird, greift die zweite Abwehr.

Die Inbox-Tabelle darf nicht unbegrenzt wachsen. Legen Sie eine Aufbewahrungsdauer fest, die länger als die längste Wiederholungsdauer des Anbieters ist (z. B. einige Wochen), und löschen Sie alte Einträge regelmäßig.

Ereignisse außer der Reihe und Versionsfeld

Das Ereignis „Bestellung versendet“ kann vor „Bestellung bestätigt“ eintreffen. Ein Empfänger, der Ereignisse in Ankunftsreihenfolge anwendet, setzt die Bestellung vom Status „versendet“ auf „bestätigt“ zurück; das Kundenkonto springt zurück, und die Support-Hotline klingelt. Es gibt drei Ansätze:

  1. Bedingte Aktualisierung mit Versions- oder Sequenznummer: Trägt das Ereignis die Version oder den Änderungszeitpunkt des Quelldatensatzes, wird nur die neuere Version angewendet.
  2. Übergangskontrolle per Zustandsautomat: Erlaubte Übergänge werden definiert; ein Übergang von „versendet“ zu „bestätigt“ wird abgelehnt und das Ereignis ignoriert.
  3. Schlankes Ereignis + erneutes Lesen: Das Ereignis enthält nur die Information „dieser Datensatz hat sich geändert“; der Empfänger liest den aktuellen Stand des Datensatzes über die API der Quelle. Das Reihenfolgeproblem entfällt, dafür kostet jedes Ereignis einen API-Aufruf.
UPDATE orders
   SET status = $1,
       source_version = $2,
       updated_at = now()
 WHERE external_id = $3
   AND source_version < $2;   -- bei alter Version werden 0 Zeilen aktualisiert

Ist die Zahl der aktualisierten Zeilen null, ist das Ereignis entweder veraltet oder der Datensatz existiert noch nicht. Um den zweiten Fall zu unterscheiden, prüfen Sie, ob der Datensatz existiert. Gibt es ihn nicht, ist es sicherer, das Ereignis mit kurzer Verzögerung erneut in die Queue zu legen, als es stillschweigend zu verwerfen.

Validierungs-Handshakes: Beispiel Microsoft Graph

Manche Anbieter prüfen beim Anlegen eines Abonnements, ob der Endpunkt tatsächlich Ihnen gehört. Bei den Change Notifications von Microsoft Graph wird beim Anlegen des Abonnements eine Anfrage mit dem Query-Parameter validationToken an den Endpunkt gesendet, und es wird erwartet, dass dieser Wert innerhalb kurzer Zeit als Klartext zurückgegeben wird. Mit jeder Benachrichtigung kommt außerdem der im Abonnement festgelegte Wert clientState; der Empfänger vergleicht ihn, um zu prüfen, dass die Benachrichtigung zu seinem eigenen Abonnement gehört. Ein Fehler, den wir in der Praxis häufig sehen: Der Empfänger unterzieht auch diese erste Anfrage der Signaturprüfung und lehnt sie ab, sodass das Abonnement nie zustande kommt. Wie die Anwendungsberechtigungen auf Graph-Seite eingeschränkt werden, beschreibt der Leitfaden zu Microsoft-Graph-API-Berechtigungen.

Test, erneutes Einspielen und Monitoring

Der Empfänger darf nicht ungetestet bleiben, bis in der Produktion das erste Ereignis eintrifft. Gehen Sie vor der Inbetriebnahme und bei jeder wichtigen Änderung diese Liste durch:

  • Wird eine Anfrage mit gültiger Signatur akzeptiert und abgelehnt, wenn im Body ein einziges Byte geändert wird?
  • Wird ein Zeitstempel außerhalb des Toleranzfensters abgelehnt?
  • Entsteht beim zweimaligen Senden desselben Ereignisses nur ein Datensatz, und erhält auch die zweite Anfrage 2xx?
  • Stimmt der Endzustand bei zwei in umgekehrter Reihenfolge gesendeten Ereignissen?
  • Liefert der Empfänger 5xx, wenn die Datenbank nicht erreichbar ist, und versucht der Anbieter es erneut?
  • Werden eine Größenbegrenzung für den Body und reiner HTTPS-Zugriff durchgesetzt?
  • Ist die Funktion zum erneuten Senden (Redelivery) eines vergangenen Ereignisses im Anbieterpanel bekannt und getestet?

Überwachen Sie in der Produktion mindestens diese Kennzahlen: empfangene Ereignisse pro Minute, Rate der Signaturfehler, Alter des ältesten Ereignisses im Status pending und Zahl der in den Fehlerstatus gefallenen Ereignisse. Fällt die Ereigniszahl zu erwarteten Zeiten auf null, ist das oft ein wichtigeres Signal als ein Anstieg der Fehlerrate. Auch Stille ist eine Störung. Die Konzeption dieses Monitorings auf Geschäftsebene finden Sie im Leitfaden zu Integrationsmonitoring und Abgleich. Zum Umfang von Webhook- und API-basierten Integrationsprojekten sehen Sie sich unsere Seite ERP-, CRM- und API-Integrationen an.

Häufig gestellte Fragen

Genügt für die Webhook-Prüfung eine IP-Allowlist?

Nein. Eine IP-Allowlist begrenzt, aus welchem Netz die Anfrage kommt; sie beweist nicht, dass der Inhalt unverändert ist oder die Anfrage nicht wiederholt eingespielt wurde. Auch die IP-Bereiche der Anbieter ändern sich mit der Zeit. Die grundlegende Prüfung ist die Signaturprüfung; eine IP-Liste bleibt, falls vorhanden, nur eine zusätzliche Schicht.

Warum passt die Signatur manchmal trotz richtigem Geheimnis nicht?

Die häufigste Ursache ist, dass die Signatur nicht über den Rohkörper, sondern über das vom Framework geparste und neu serialisierte JSON berechnet wird. Ändern sich Leerzeichen, Feldreihenfolge oder Unicode-Escapes, ändert sich auch der Hash. Weitere Ursachen sind falsche Zeichenkodierung, nicht entfernte Präfixe im Header wie sha256= und eine abweichende Serveruhr.

Welchen HTTP-Code sollte ein Webhook-Empfänger im Fehlerfall liefern?

Bei ungültiger Signatur 401 oder 403, bei fehlerhafter Anfrage 400. Wurde das Ereignis dauerhaft gespeichert oder bereits früher gespeichert, wird 200 oder 202 geliefert. 5xx wird nur bei vorübergehenden Infrastrukturfehlern beim Speichern verwendet; Fehler in der Geschäftslogik werden nicht an den Absender gespiegelt, sondern auf Empfängerseite behandelt.

Wie lange sollten Einträge in der Tabelle der Ereignis-IDs gehalten werden?

Länger als die längste vom Anbieter dokumentierte Wiederholungsdauer. In der Praxis genügen in den meisten Szenarien einige Wochen. Sind die Operationen zusätzlich idempotent gestaltet, beschädigt auch ein seltenes Duplikat nach dem Bereinigen alter Einträge die Daten nicht.

Support

Kontaktieren Sie uns für Support oder eine Bestandsaufnahme zu diesem Thema.

Kontaktformular
[email protected]

Eretek Web

Wir bauen Unternehmenswebsites, WordPress- und CMS-Plattformen, Intranet- und SharePoint-Portale, Dokumentenmanagement sowie Formular- und Freigabeprozesse auf und halten sie sicher und aktuell.

Wissenszentrum

Weitere Beiträge