OpenClaw Webhook HTTP 202 | Nginx, Caddy, Health-Checks Linux VPS

Wenn Sie OpenClaw hinter TLS auf einem Linux-VPS betreiben, wirken Webhooks oft wie ein simpler POST — bis ein Dienst strikt HTTP 200 erwartet, Ihr Gateway aber 202 Accepted zurückgibt. RFC-seitig ist 202 korrekt für asynchrone Annahme; in der Praxis brechen manche SaaS-Retrier, Signatur-Verifier oder interne „success = 200"-Guards trotzdem. Dieser Artikel fasst ein reproduzierbares Vorgehen zusammen: Symptom isolieren, Reverse-Proxy-Strategie wählen und Health-Checks entkoppeln.

202

RFC-konform, nicht immer „Integration OK"

GET

Health-Sonden getrennt vom Webhook-Pfad

TLS

Nginx oder Caddy vor dem Gateway

1. Symptom: alles lokal grün, Produktion rot

Typisches Muster: curl -vk https://ihre-domain/webhook zeigt 202 und einen kleinen JSON-Body, OpenClaw-Logs bestätigen die Queueing-Logik — aber der Drittanbieter meldet „Webhook failed" oder wiederholt Events endlos. Prüfen Sie zuerst Statuscode, Content-Type und Antwortzeit getrennt: manche Plattformen parsen nur bei 200, andere hängen an exakter Signatur über den Roh-Body (ein Proxy, der den Body neu serialisiert, kann dann scheitern, selbst wenn der Code 200 wird).

Risiko vorweg

Ein reines Umschreiben des Statuscodes verschleiert Semantik: Clients könnten künftig Retries anders erwarten. Dokumentieren Sie die Ausnahme im Runbook und planen Sie eine saubere Upstream-Korrektur ein, sobald der Anbieter 202 akzeptiert oder Sie eine dedizierte Callback-Route bereitstellen können.

2. Entscheidungsmatrix: Upstream vs. Proxy vs. Adapter

Die Matrix unten hilft, ohne Trial-and-Error die geringste Komplexität zu wählen — besonders wenn Loadbalancer- oder Kubernetes-Sonden auf demselben Hostnamen landen.

Ausgangslage	Empfohlene erste Maßnahme	Trade-off
OpenClaw/Gateway kann Status konfigurieren	Auf 200 stellen oder zweite Route nur für diesen Partner	Geringster Proxy-Magic; am saubersten auditierbar
Kein schneller Upstream-Fix, Caddy 2.x	`handle_response` bei 202 auf 200 mappen	Native Lösung, gut lesbar; Caddy-Version beachten
Nginx OSS ohne Lua	Kleinen lokalen Adapter (127.0.0.1) oder OpenResty-Lua	Stock-Nginx kann Response-Status nicht frei patchen
LB-Sonde trifft Webhook-Pfad	Eigenen /healthz-GET mit 200, ACL nur intern	Verhindert falsche „rot"-Events bei POST-only-Pfaden

3. Caddy und Nginx/OpenResty: konkrete Muster

Caddy kann auf eingehende Upstream-Antworten reagieren. Ein übliches Muster ist, nur den Status anzupassen und Header/Body unangetastet zu lassen — so bleiben Signaturketten stabil, solange der Proxy nicht neu encodiert:

Caddy (Ausschnitt): 202 → 200 für einen Webhook-Upstream

reverse_proxy 127.0.0.1:18789 {
  @hook202 {
    status 202
  }
  replace_status @hook202 200
}

Nginx (Community) bietet ohne Erweiterungen keinen zuverlässigen „map response status"-Schalter. Pragmatisch: entweder OpenResty mit kurzem header_filter_by_lua_block oder ein Mini-Service auf Loopback, der transparent durchreicht und nur den Code normalisiert. Beispiel Lua (nur wenn Sie ohnehin OpenResty fahren):

OpenResty: Status 202 auf 200 setzen

header_filter_by_lua_block {
  if ngx.status == 202 then ngx.status = 200 end
}

Health-Sonden entkoppeln

Richten Sie Sonden auf GET /healthz (statischer 200) oder einen separaten Port, der nur intern erreichbar ist. Wenn dieselbe location POST-Webhooks und GET-Sonden mischt, sehen Sie im Grafana oft „200/202-Chaos", obwohl das Gateway gesund ist — das erschwert Postmortems.

4. Reproduzierbares Mini-Protokoll

Direkt gegen Loopback testen: curl -i http://127.0.0.1:PORT/webhook (ohne TLS), um OpenClaw isoliert zu sehen.
Dann durch den Proxy mit SNI: gleiche URL wie der Partner, --resolve oder /etc/hosts.
Parallel Access-Log des Proxies mit $status und Upstream-Time; Abweichungen markieren Buffering oder Timeouts.
Sobald 200 stabil ist, erneut beim Partner „verify webhook" klicken — viele speichern den zuletzt gesehenen Statuscode.

5. FAQ

Ist 202 nicht „besser" als 200 für lange Jobs?

Semantisch ja — aber nur, wenn alle Beteiligten es so interpretieren. Für harte 200-Checker ist ein klarer Vertrag wichtiger als RFC-Purismus.

Warum schlägt es erst nach dem Proxy fehl?

Häufige Ursachen: doppelte gzip, Body-Größenlimit, falsches proxy_request_buffering, oder eine Sonde, die POST ohne Payload sendet und 4xx erzeugt.

Darf ich einfach alles auf 200 mappen?

Nur wenn Fehler weiterhin als 4xx/5xx sichtbar bleiben und Sie keine Retry-Stürme riskieren. Für 5xx bitte nie „kosmetisch" auf 200 umbiegen.

Vertiefung zu harter Oberfläche und Loopback-Only-Verwaltung: 2026 OpenClaw Linux-Cloud-VPS: Minimale Angriffsfläche — Firewall-Vorlage, Gateway-Loopback-Bindung und SSH-Tunnel … sowie Mehrkanal-Bots und Berechtigungen: 2026 OpenClaw mit Telegram und Discord im Doppelkanal …