10 Webhook-Best-Practices

Als Empfänger

1. Innerhalb von Sekunden antworten

Validieren, in die Queue, 2xx zurück. Alles Langsame passiert danach. Timeouts sind Ursache Nummer eins für „Phantom“-Retries.

2. Idempotent sein

Über die Ereignis-ID deduplizieren – dasselbe Ereignis wird zweimal ankommen. Das Muster.

3. Signaturen prüfen

Über den rohen Body, mit timing-sicherem Vergleich, inklusive Zeitstempel-Prüfung. Details.

4. Ehrliche Statuscodes zurückgeben

5xx, wenn du einen Retry willst, 2xx, wenn nicht. Die Tabelle.

5. Jede Zustellung protokollieren

Header, Body, deine Antwort, Zeitstempel. Wenn in drei Wochen etwas fehlt, ist dieses Log das Einzige, was „ist es überhaupt angekommen?“ beantwortet.

6. Defensiv auf den Payload zugreifen

Optionale Felder verschwinden, neue tauchen auf. Nie von einer festen Form ausgehen. Payload-Guide.

7. Mit dem eigenen Ausfall rechnen

Anbieter wiederholen eine Weile und hören dann auf – manchmal deaktivieren sie den Endpoint. Kenne das Zeitfenster deines Anbieters und prüfe nach einem Ausfall auf verpasste Ereignisse.

Als Absender

8. Retries mit exponentiellem Backoff

Sekunden, Minuten, Stunden – nicht jede Sekunde. Und irgendwann aufhören, mit Hinweis an den Betreiber des Endpoints.

9. Payloads signieren und Zeitstempel mitschicken

Gib Empfängern eine Möglichkeit, dir zu vertrauen, und mach Replay-Angriffe erkennbar.

10. Payloads klein und stabil halten

IDs und das Wesentliche senden; Details holen sich Empfänger per API. Felder ergänzen, nicht umbenennen – Umbenennungen brechen alle Empfänger gleichzeitig.

Die Meta-Regel

Pass den Aufwand den Konsequenzen an. Ein Webhook, der Konten freischaltet, verdient alle zehn Regeln. Ein Webhook, der dein Handy klingeln lässt, wenn ein Build scheitert, verdient eine lange Zufalls-URL und eine schnelle Antwort – und das ist völlig in Ordnung. Benachrichtigungs-Klempnerei zu überkonstruieren ist auch ein Fehler.

Neu im Thema? Starte hier: Was ist ein Webhook.

Hol dir Webhooky

Kostenlos für deine ersten 100 Benachrichtigungen – Endpoint in zwei Minuten eingerichtet.