Nehmen Sie einen Webhook über HTTPS entgegen, prüfen Sie die Signatur über den ursprünglichen Body und den Zeitstempel der Nachricht, validieren Sie das Schema und speichern Sie das Ereignis mit einer eindeutigen ID. Antworten Sie schnell und verarbeiten Sie es idempotent in einer Warteschlange. Rechnen Sie mit Duplikaten und veränderter Reihenfolge, überwachen Sie Fehler und gleichen Sie kritische Daten regelmäßig ab.
Ein Webhook ist eine Nachricht, mit der ein System einem anderen ein Ereignis mitteilt, zum Beispiel eine eingegangene Zahlung, eine Änderung der Sendung oder einen neuen Kontakt. Im Vergleich zur regelmäßigen Statusabfrage kann er schnell und mit weniger Anfragen reagieren. Die Zustellung über das Internet ist jedoch keine perfekt geordnete Reihenfolge: Eine Nachricht kann mehrfach, verspätet, gleichzeitig oder gar nicht ankommen. Der Empfänger muss mit diesen Eigenschaften rechnen.
Ein sicherer Endpoint darf auch nicht beliebigem JSON vertrauen, nur weil es korrekt aussieht. Er prüft Herkunft, Integrität, Zeitpunkt, Format und Berechtigung des Ereignisses. Die Verarbeitung trennt die schnelle Annahme von der langsamen Geschäftslogik und erhält die Beobachtbarkeit. Der folgende Entwurf ist für WordPress, WooCommerce und eine eigenständige Anwendung einsetzbar.
Definieren Sie den Vertrag und den Lebenszyklus des Ereignisses
Dokumentieren Sie Ereignistypen, Version, eindeutige ID, Entstehungszeitpunkt, Objektidentität und Datenschema. Unterscheiden Sie, ob der Payload (Nachrichtentext) das vollständige aktuelle Objekt enthält oder nur eine Benachrichtigung, nach der die API aufgerufen werden muss. Bei einem vollständigen Objekt kann ein verspätet eintreffendes älteres Ereignis einen neueren Zustand überschreiben; beim anschließenden API-Aufruf müssen wiederum Limits und Nichtverfügbarkeit bewältigt werden. Die Wahl hängt vom Anbieter und der erforderlichen Konsistenz ab.
Ereignisse haben den Status empfangen, verifiziert, wartend, verarbeitet oder fehlerhaft. Speichern Sie den ursprünglichen Body entsprechend seiner Sensibilität und begrenzen Sie die Aufbewahrungsdauer. Eine eindeutige ID schützt vor Duplikaten, eine Korrelations-ID verknüpft die Folgeschritte. Definieren Sie End- und Zwischenzustände des Geschäftsobjekts, damit eine verspätete Nachricht „Zahlung ausstehend“ eine bereits bezahlte Bestellung nicht zurücksetzt.
Prüfen Sie die Signatur und verhindern Sie wiederholten Missbrauch
Prüfen Sie die Signatur genau nach der Dokumentation des Anbieters, in der Regel anhand des unveränderten Anfragekörpers und eines Zeitstempels. Formatiert das Framework den Body zuvor um, kann die resultierende Signatur abweichen. Führen Sie den Vergleich auf sichere Weise durch und weisen Sie ungültige Nachrichten vor der geschäftlichen Verarbeitung zurück. Speichern Sie das Secret in einer sicheren Konfiguration, verwenden Sie getrennte Werte für die einzelnen Umgebungen und bereiten Sie eine Rotation vor.
Ein Zeitfenster und die Erfassung von IDs verringern das Risiko, dass eine abgefangene gültige Nachricht erneut eingespielt wird. Eine IP-Allowlist kann eine zusätzliche Schutzschicht sein, wenn der Anbieter stabile Adressbereiche veröffentlicht, jedoch nicht der einzige Nachweis der Herkunft. Begrenzen Sie den Endpoint hinsichtlich Body-Größe, unterstützter Methoden und Rate-Limit. Fehlerantworten geben weder Stacktraces noch Secrets preis. Bei einem eigenen Absender schützen Sie Empfänger und Signaturschlüssel auf die gleiche Weise.
- HTTPS und Signatur über den ursprünglichen Body
- Zeittoleranz und eindeutige ID
- Getrennte Geheimnisse und Rotationsplan
- Begrenzung von Größe, Methoden und Häufigkeit
Antworten Sie schnell und verarbeiten Sie in einer Warteschlange
Der Endpoint sollte das Ereignis prüfen und dauerhaft speichern und anschließend schnell einen Erfolg zurückmelden. Erzeugt er innerhalb einer einzigen Anfrage ein Dokument, ruft drei APIs auf und versendet eine E-Mail, kann der Anbieter ein Timeout feststellen und das Ereignis erneut senden. Eine Warteschlange trennt den Empfang von der Verarbeitung, ermöglicht eine Begrenzung der Parallelität und bewahrt die Nachricht bei einem vorübergehenden Ausfall einer Abhängigkeit. Senden Sie die Bestätigung jedoch erst nach dem sicheren Speichern, nicht davor.
Der Worker verwendet eine idempotente Operation und prüft den aktuellen Zustand des Objekts. Einen vorübergehenden Fehler wiederholt er mit zunehmendem Abstand, einen dauerhaften Schema- oder Berechtigungsfehler verschiebt er in die Quarantäne. Die Anzahl der Versuche und das Alter eines Ereignisses sind begrenzt. Die Administration oder ein Dashboard ermöglicht es, eine korrigierte Nachricht sicher erneut zu verarbeiten, ohne die Datenbank manuell zu ändern. Bei strenger Reihenfolge verarbeiten Sie Ereignisse pro Objekt sequenziell oder verwenden eine Zustandsversion.
Respektieren Sie beim Versand den Empfänger
Versenden Sie eigene Webhooks mit klarer Dokumentation, Version und Signatur. Validieren Sie den Empfänger-Endpoint bei der Registrierung und lassen Sie eine sensible Adressänderung bestätigen. Legen Sie ein Timeout, eine begrenzte Anzahl von Versuchen und ein exponentielles Backoff mit Jitter fest. Definieren Sie Erfolg anhand des vereinbarten Bereichs von Statuscodes. Wiederholen Sie einen dauerhaften Client-Fehler nicht endlos, sondern machen Sie den Grund für den Verantwortlichen der Integration einsehbar.
Jeder Abonnent hat ein eigenes Secret und kann pausiert werden, ohne die anderen zu beeinflussen. Protokollieren Sie Ereignis-ID, Ziel, Versuch, Zeitpunkt und ein sicheres Ergebnis. Minimieren Sie den Payload und stellen Sie sensible Daten lieber über einen authentifizierten nachfolgenden API-Aufruf bereit, sofern das Modell dies zulässt. Fügen Sie bei einer Schemaänderung eine Version und eine Übergangsfrist hinzu; eine stille Inkompatibilität ist gefährlicher als eine explizit abgelehnte neue Version.
- Ein eigenes Secret für jeden Empfänger
- Timeout und kontrollierte Wiederholung
- Versionierter Payload mit minimalen Daten
- Möglichkeit zum Pausieren und erneuten Zustellen
Testen und gleichen Sie kritische Daten ab
Die Tests decken gültige und ungültige Signaturen, veraltete Zeitstempel, Duplikate, Nebenläufigkeit, geänderte Reihenfolge, beschädigtes JSON, Timeouts und Fehler in Abhängigkeiten ab. Stellen Sie Entwicklern eine sichere Möglichkeit bereit, Testereignisse zu wiederholen, sowie Beispiel-Payloads ohne personenbezogene Produktionsdaten. Achten Sie bei einem lokalen Tunnel auf die Zugriffskontrolle und schalten Sie ihn nach dem Test ab. Ein Lasttest prüft sowohl die Queue als auch den Schutz des Endpoints.
Das Monitoring verfolgt die Raten für Empfang, Prüfung und Verarbeitung, die Anzahl der Wiederholungen, das Alter der Warteschlange und die Quarantäne. Gleichen Sie kritische Daten regelmäßig über die API oder einen Export ab, denn ein Webhook muss nicht die einzige Quelle der Wahrheit sein. Wird eine Abweichung festgestellt, korrigiert der Prozess sie oder legt sie einem Menschen vor. Ein Runbook erklärt, wo das Ereignis zu finden ist, wie der Status beim Anbieter überprüft wird und wann eine Wiederholung sicher ist.
Häufige Fragen
Was ist der Unterschied zwischen API und Webhook?
Eine API wird in der Regel aufgerufen, wenn der Client Daten oder eine Aktion anfordert; einen Webhook löst der Anbieter bei einem Ereignis aus. Häufig werden beide kombiniert: Der Webhook meldet eine Änderung, und der Empfänger ruft über die API den verifizierten aktuellen Stand ab.
Warum kam der Webhook zweimal an?
Der Anbieter kann die Zustellung nach einem Timeout oder einer fehlenden Bestätigung wiederholen, und das Netzwerk kann nicht genau einen Versuch garantieren. Der Empfänger muss Ereignis-IDs und eine idempotente Verarbeitung verwenden, statt von einer einzigen Zustellung auszugehen.
Sollte ein Endpoint immer Erfolg zurückgeben?
Nein. Eine ungültige Signatur oder ein ungültiges Schema muss mit einem angemessenen Status abgelehnt werden. Bestätigen Sie ein gültiges Ereignis erst nach dessen sicherer Speicherung. Die konkrete Antwort und die Wiederholungsregeln richten sich nach der Dokumentation des Anbieters und Ihrem Vertrag.
Quellen und weiterführende Lektüre
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
