HTTP-Statuscodes für Webhooks
23. Juli 2026 · 3 Min. Lesezeit
Der Statuscode, den du zurückgibst, ist keine Dekoration – er ist eine Anweisung an den Absender. Der falsche Code ist der Grund, warum Endpoints deaktiviert werden, Ereignisse verschwinden oder derselbe Request drei Tage lang deinen Server bearbeitet.
Die kurze Tabelle
| Code | Bedeutung für den Absender | Nimm ihn, wenn |
|---|---|---|
| 200 OK | Empfangen und verarbeitet. Erledigt. | die Standardantwort |
| 202 Accepted | Empfangen, Verarbeitung folgt. | du den Job in eine Queue gelegt hast – die ehrliche Antwort bei asynchroner Verarbeitung |
| 204 No Content | Empfangen, nichts zu sagen. | wie 200, nur ohne Body |
| 400 Bad Request | Kaputter Payload – meist kein Retry. | der Body wirklich nicht parsbar ist |
| 401 / 403 | Nicht berechtigt – meist kein Retry. | die Signaturprüfung fehlschlägt |
| 404 | Endpoint existiert nicht. Deaktiviert den Webhook oft. | nie absichtlich |
| 410 Gone | Endpoint dauerhaft weg. Nicht mehr senden. | du ihn bewusst abgeschaltet hast |
| 429 | Zu viele Anfragen – später erneut. | du rate-limitierst |
| 500 / 503 | Vorübergehender Fehler – bitte erneut. | deine Datenbank streikt, eine Abhängigkeit fehlt |
Die Faustregel
2xx = nicht nochmal senden. 4xx = nicht nochmal senden, es lag an uns. 5xx = später nochmal senden. Das ist die ganze Logik. Alles andere ist Feinheit.
Die Fehler, die wehtun
- 500 bei kaputtem Payload. Der Anbieter wiederholt einen Request, der nie gelingen kann – stunden- oder tagelang.
- 200 zurückgeben, obwohl die Verarbeitung scheiterte. Das Ereignis ist für immer weg; der Anbieter hält es für zugestellt. Kannst du es nicht verarbeiten, sag 500 und lass den Retry für dich arbeiten.
- Langsam antworten. Die meisten Anbieter brechen nach 5–30 Sekunden ab und werten das als Fehlschlag – auch wenn dein Code fertig wurde.
- 4xx bei aufgebrauchtem Kontingent. Vorsicht: Der Absender kann den Endpoint nach genügend Fehlschlägen deaktivieren. War der Request selbst in Ordnung, ist ein 2xx mit Erklärung im Body freundlicher – genau das macht Webhooky, wenn ein Gratis-Limit erreicht ist.
202 ist unterschätzt
Wenn du Arbeit in eine Queue legst und sofort antwortest, ist 202 Accepted treffender als 200 OK: „Ich hab's, ich kümmere mich.“ Anbieter werten beides als Erfolg, und deine Logs bleiben ehrlich darüber, was tatsächlich passiert ist.
Mehr: Retries und Idempotenz · Best Practices
Hol dir Webhooky
Kostenlos für deine ersten 100 Benachrichtigungen – Endpoint in zwei Minuten eingerichtet.
