Webhooks

Beim API-Polling fragt das empfangende System das Quellsystem in festen Intervallen (alle 1 Minute, alle 5 Minuten) wiederholt: „Hat sich etwas geändert?“. Dies ist ineffizient: Die meisten Polling-Anfragen liefern „keine Änderungen“, verbrauchen API-Kontingent und erzeugen Latenz (die maximale Latenz entspricht dem Polling-Intervall). Webhooks kehren das Modell um: Das Quellsystem benachrichtigt den Empfänger sofort, wenn ein Ereignis auftritt, wodurch eine nahezu null Latenz ohne verschwendete API-Aufrufe erreicht wird. Die Einschränkung ist die Zuverlässigkeit: Webhooks sind standardmäßig „Fire and Forget“ – wenn das empfangende System ausgefallen ist, gehen Ereignisse verloren. Gut konzipierte Webhook-Systeme fügen eine Wiederholungslogik mit exponentiellem Backoff (mehrere Zustellversuche in zunehmenden Intervallen) und Zustellungsprotokolle (sichtbar in der Produkt-UI, damit Kunden überprüfen können, ob ihr Endpunkt jedes Ereignis empfangen hat und Fehler untersuchen können) hinzu.

Webhook-Fehler gehören zu den komplexesten Support-Tickets für Integrationen, da sie beide Seiten der Integration betreffen. Häufige Szenarien: (1) Endpunkt empfängt keine Ereignisse – überprüfen Sie, ob die Endpunkt-URL öffentlich zugänglich ist (nicht localhost), der Server das Testereignis akzeptiert hat und der Ereignistyp abonniert ist. (2) HTTP 200-Antwort nicht zurückgegeben – der empfangende Server muss innerhalb des Timeout-Fensters (typischerweise 10–30 Sekunden) einen HTTP 200-Status zurückgeben; dauert es länger, markiert die Webhook-Plattform die Zustellung als fehlgeschlagen, selbst wenn der Server das Ereignis schließlich verarbeitet hat. (3) Duplizierte Ereignisse – gut konzipierte Webhook-Konsumenten sollten idempotent sein (das zweimalige Verarbeiten desselben Ereignisses führt zum gleichen Ergebnis wie das einmalige Verarbeiten), indem sie die eindeutige ID des Ereignisses verwenden, um Duplikate zu erkennen und zu ignorieren. (4) Signaturprüfung fehlgeschlagen – die meisten SaaS-APIs signieren Webhook-Payloads mit HMAC-SHA256 unter Verwendung eines geheimen Schlüssels; der Code des Kunden muss diese Signatur bei jedem empfangenen Ereignis überprüfen, um gefälschte Webhook-Angriffe zu verhindern.

Product Ops arbeitet mit dem Engineering zusammen, um Webhook-Funktionen zu entwickeln, die den Support-Aufwand minimieren und die Zufriedenheit der Entwickler maximieren. Best Practices: Abdeckung der Ereignistypen (jede bedeutsame Zustandsänderung im Produkt sollte ein entsprechendes Webhook-Ereignis haben); Design der Ereignis-Payload (Payloads sollten alle Daten enthalten, die zur Reaktion auf das Ereignis erforderlich sind, ohne einen nachfolgenden API-Aufruf – den vollständigen Objektzustand einschließen, nicht nur IDs, die eine nachfolgende GET-Anfrage erfordern); UI für Zustellungsprotokolle (ein durchsuchbares Ereignisprotokoll im Produkt-Dashboard, in dem Entwickler jedes ausgelöste Ereignis, seinen Zustellstatus, die HTTP-Antwort des Servers und eine Schaltfläche „erneut zustellen“ für manuelle Wiederholung sehen können); Signaturprüfung (jede Payload mit HMAC-SHA256 signieren und den Verifizierungsprozess klar dokumentieren); und versionierte Payloads (wenn sich das Ereignisschema ändern muss, die Payload versionieren und beide Versionen während einer Übergangszeit gleichzeitig unterstützen – niemals breaking changes an einer Webhook-Payload ohne vorherige Ankündigung vornehmen).