Minimaler Webhook-Empfänger mit netcat in Bash bauen

1. Warum ein Webhook-Empfänger mit netcat sinnvoll ist

Bevor ein Webhook produktiv in eine Anwendung integriert wird, muss zuerst geklärt werden, was der Absender überhaupt schickt: welche Header, welches Content-Type, welches JSON-Schema, welche Signatur. Ein vollwertiger Webserver mit Routing und Middleware ist für diese Phase Overkill. Ein minimaler Webhook-Empfänger mit netcat beantwortet genau diese Frage in Sekunden, ohne ein Projekt aufzusetzen oder einen Port in einer bestehenden Anwendung freizuschalten.

netcat, kurz nc, ist auf praktisch jedem Linux-System vorhanden und öffnet mit einem einzigen Aufruf einen TCP-Listener auf einem beliebigen Port. Kombiniert mit einer Bash-Schleife entsteht daraus ein Webhook-Empfänger mit netcat, der jeden eingehenden Request komplett anzeigt, inklusive aller Header, die viele Webhook-Anbieter zur Signaturprüfung verwenden. Das ist besonders wertvoll, wenn die Dokumentation eines Drittanbieters lückenhaft ist und man wissen muss, was tatsächlich über die Leitung kommt.

Auch in Verbindung mit einem Tunnel-Dienst wie ngrok oder cloudflared ist ein solcher Empfänger nützlich: Der Tunnel leitet den öffentlichen Webhook-Request an den lokalen netcat-Listener weiter, und man sieht in Echtzeit, was ein externer Dienst tatsächlich sendet, bevor man eine einzige Zeile Anwendungscode schreibt.

2. Netcat-Grundlagen: nc -l, Ports und Varianten

Der Grundbefehl für einen Webhook-Empfänger mit netcat ist nc -l -p 8080 bei der traditionellen Variante (Debian/Ubuntu, Paket netcat-traditional) oder nc -l 8080 bei der OpenBSD-Variante, die auf vielen anderen Distributionen und macOS Standard ist. Der Unterschied in der Optionssyntax ist einer der häufigsten Stolpersteine: -p für den Port existiert nur bei der traditionellen Variante, während OpenBSD-nc den Port als positionales Argument erwartet.

Ein einzelner nc -l-Aufruf nimmt genau eine Verbindung entgegen und beendet sich danach. Für einen dauerhaften Webhook-Empfänger mit netcat braucht es deshalb eine Endlosschleife, die nc nach jeder Verbindung neu startet. Die Option -k (keep listening) existiert zwar bei manchen nc-Varianten, verhält sich aber uneinheitlich zwischen Implementierungen, weshalb eine explizite Bash-Schleife die portablere und nachvollziehbarere Lösung ist.

#!/usr/bin/env bash
# detect-netcat.sh — identify which netcat variant is installed
set -euo pipefail

if nc -h 2>&1 | grep -q "\-\-version"; then
  echo "[INFO] Likely OpenBSD netcat: use 'nc -l PORT'"
elif nc -h 2>&1 | grep -q "\-p port"; then
  echo "[INFO] Likely traditional netcat: use 'nc -l -p PORT'"
else
  echo "[WARN] Could not reliably detect nc variant, test both syntaxes"
fi

nc -h 2>&1 | head -n 3

3. Einen einfachen HTTP-Empfänger mit einer while-Schleife bauen

Ein Webhook-Empfänger mit netcat braucht zwei Bausteine: einen Listener, der Requests entgegennimmt, und eine feste HTTP-Antwort, die zurückgeschrieben wird, sobald der Request eingetroffen ist. Die einfachste Form liest den kompletten Request in eine Datei, gibt eine minimale 200 OK-Antwort zurück und startet den Listener danach erneut in einer Schleife.

Wichtig ist die Reihenfolge: nc muss die Response schreiben, bevor die Verbindung geschlossen wird, sonst wartet der Webhook-Absender auf eine Antwort, die nie kommt, und meldet nach seinem eigenen Timeout einen Fehlschlag. Mit tee lässt sich der eingehende Request gleichzeitig protokollieren und für die Response-Logik auswerten.

#!/usr/bin/env bash
# webhook-receiver.sh — minimal webhook receiver built on netcat
set -euo pipefail

PORT="${1:-8080}"
LOG_DIR="/tmp/webhook-logs"
mkdir -p "$LOG_DIR"

echo "[INFO] Listening for webhooks on port $PORT (Ctrl+C to stop)"

while true; do
  request_file="$LOG_DIR/request-$(date +%s%N).log"

  # Capture the raw request, then send a fixed 200 OK response
  {
    printf 'HTTP/1.1 200 OK\r\n'
    printf 'Content-Type: text/plain\r\n'
    printf 'Content-Length: 2\r\n'
    printf 'Connection: close\r\n'
    printf '\r\n'
    printf 'OK'
  } | nc -l -p "$PORT" -q 1 > "$request_file" 2>/dev/null || true

  echo "[INFO] Request captured: $request_file"
  head -n 5 "$request_file"
  echo "---"
done

Dieses Skript ist bewusst minimal: Ein Webhook-Empfänger mit netcat für Debugging-Zwecke muss keine echte Routing-Logik enthalten, es reicht, den Request sichtbar zu machen. Die Option -q 1 weist nc an, eine Sekunde nach dem Ende der Eingabe die Verbindung zu schließen, was verhindert, dass der Prozess unendlich auf weitere Daten wartet.

4. Korrekte HTTP-Response-Header zurückschreiben

Viele Webhook-Absender prüfen den HTTP-Statuscode der Antwort und wiederholen den Request bei allem außer 2xx. Ein Webhook-Empfänger mit netcat, der nur Rohdaten ohne gültige HTTP-Header zurückschreibt, wird deshalb vom Absender als Fehler interpretiert, selbst wenn der Request korrekt empfangen wurde. Die Response muss zwingend mit der Statuszeile beginnen, gefolgt von den Headern, einer Leerzeile und optional einem Body, jeweils mit CRLF (\r\n) als Zeilenende, nicht mit reinem \n.

Der Header Content-Length muss exakt der Byte-Länge des Response-Bodys entsprechen, sonst warten manche HTTP-Clients auf weitere Bytes, bis der eigene Timeout greift. Wer testen will, ob ein Webhook-Anbieter auf bestimmte Statuscodes anders reagiert, kann diesen Wert im Skript einfach parametrisieren und verschiedene Antworten (200, 400, 500) gezielt durchspielen.

#!/usr/bin/env bash
# webhook-receiver-status.sh — reply with a configurable HTTP status
set -euo pipefail

PORT="${1:-8080}"
STATUS="${2:-200 OK}"
BODY="${3:-{"received":true}}"
BODY_LENGTH=${#BODY}

response=$(printf 'HTTP/1.1 %s\r\nContent-Type: application/json\r\nContent-Length: %d\r\nConnection: close\r\n\r\n%s' "$STATUS" "$BODY_LENGTH" "$BODY")

echo "[INFO] Replying with: HTTP/1.1 $STATUS"
printf '%s' "$response" | nc -l -p "$PORT" -q 1

5. Content-Length lesen und Payload extrahieren

Ein empfangener Webhook-Request besteht aus Statuszeile, Headern, einer Leerzeile und dem eigentlichen Body, üblicherweise JSON. Um den Body sauber aus der aufgezeichneten Datei zu extrahieren, sucht man die erste leere Zeile und gibt alles danach aus. In Bash übernimmt das awk in einer einzigen Anweisung zuverlässig, unabhängig davon, wie viele Header der Absender mitschickt.

Der Header Content-Length gibt vor, wie viele Bytes im Body folgen. Bei einem Webhook-Empfänger mit netcat ist das wichtig, weil TCP keine Nachrichtengrenzen kennt: Ohne Content-Length weiß man nicht sicher, ob der komplette Body bereits angekommen ist oder der Client noch mehr Daten sendet. Für Debugging-Zwecke reicht es meist, den Wert zu protokollieren und mit der tatsächlichen Body-Länge zu vergleichen.

#!/usr/bin/env bash
# parse-webhook.sh — extract headers, content-length, and JSON body
set -euo pipefail

REQUEST_FILE="${1:?Usage: parse-webhook.sh <request-file>}"

# Everything before the first blank line is headers
headers=$(awk '/^\r?$/{exit} {print}' "$REQUEST_FILE")
content_length=$(echo "$headers" | grep -i '^Content-Length:' | awk '{print $2}' | tr -d '\r')

# Everything after the first blank line is the body
body=$(awk 'BEGIN{found=0} /^\r?$/{found=1; next} found{print}' "$REQUEST_FILE")

echo "[INFO] Declared Content-Length: ${content_length:-unknown}"
echo "[INFO] Actual body length: ${#body}"

if command -v jq &>/dev/null && [[ -n "$body" ]]; then
  echo "$body" | jq . 2>/dev/null || echo "[WARN] Body is not valid JSON"
fi

6. Persistenter Empfänger mit systemd statt Einzelaufruf

Für gelegentliches Debugging reicht ein Skript, das man manuell im Terminal startet. Soll ein Webhook-Empfänger mit netcat aber über mehrere Tage auf einem Test- oder Staging-Server laufen, ist ein systemd-Service die robustere Lösung: Er startet automatisch nach einem Absturz neu, läuft im Hintergrund und schreibt Logs über journalctl statt in eine lose Textdatei.

Die Unit-Datei ruft einfach das Empfänger-Skript mit Restart=always auf. Das verhindert, dass eine einzelne fehlerhafte Verbindung, die nc abstürzen lässt, den gesamten Debugging-Empfänger dauerhaft lahmlegt. Für produktivere Zwecke sollte dieser Ansatz trotzdem nur temporär bleiben, siehe Abschnitt sieben zu den Sicherheitsgrenzen.

7. Sicherheit: warum netcat nie produktionsreif ist

Ein Webhook-Empfänger mit netcat ist ein Debugging-Werkzeug, kein Produktionsdienst. Es fehlt jegliche Signaturprüfung, TLS-Terminierung, Rate-Limiting und Fehlerbehandlung bei parallelen Verbindungen. Ein einzelner nc-Prozess kann in der einfachsten Form immer nur eine Verbindung gleichzeitig bearbeiten, was bei mehreren gleichzeitig eintreffenden Webhooks zu verlorenen Requests führt, ohne dass der Absender das bemerkt.

Wichtiger noch: Ohne Prüfung der Signatur, die die meisten Webhook-Anbieter im Header mitschicken (etwa X-Hub-Signature-256 bei GitHub oder Stripe-Signature bei Stripe), akzeptiert ein solcher Empfänger jeden beliebigen Request, auch gefälschte. Für lokales Debugging spielt das keine Rolle, für jede produktive Nutzung ist ein Webhook-Empfänger mit netcat aber grundsätzlich ungeeignet und sollte nie über das eigene Entwicklernetzwerk hinaus erreichbar sein.

8. Eingehende Webhooks von GitHub, Stripe und GitLab lokal debuggen

Die drei häufigsten Webhook-Quellen im Alltag eines Entwicklers sind GitHub (Push- und Pull-Request-Events), GitLab (Pipeline- und Merge-Request-Events) und Stripe (Zahlungsereignisse). Alle drei senden strukturiertes JSON mit einer Signatur im Header. Ein Webhook-Empfänger mit netcat, kombiniert mit einem Tunnel-Tool wie ngrok, zeigt genau, welche Felder tatsächlich im Payload stehen, oft abweichend von veralteten Dokumentationsbeispielen.

Besonders hilfreich ist das bei Stripe, wo sich Event-Schemas zwischen API-Versionen unterscheiden können. Statt gegen die Produktions-API zu entwickeln, konfiguriert man den Webhook testweise auf die lokale ngrok-URL, die den Empfänger mit netcat erreicht, und sieht in Echtzeit jedes gesendete Event mit vollständigem Body. Das verkürzt die Integrationszeit erheblich, weil man nicht zwischen Dashboard, Logs und Code hin- und herspringen muss.

9. netcat vs. socat vs. Mini-Server im Vergleich

Für reines Anschauen von Rohdaten bleibt netcat die schnellste Option, weil kein zusätzliches Paket installiert werden muss. Sobald mehrere Verbindungen gleichzeitig ankommen sollen, etwa bei Lasttests mit mehreren simulierten Webhook-Absendern, ist socat mit seinen flexibleren Fork-Optionen die bessere Wahl, weil es Verbindungen parallel statt nacheinander verarbeitet.

Ein kleiner Python-Server mit http.server oder eine winzige Node-Anwendung liefert vollständige HTTP-Konformität inklusive korrektem Chunked-Encoding und HTTP/1.1-Keep-Alive, was ein Webhook-Empfänger mit netcat nicht bietet. Für die allererste Sichtprüfung eines unbekannten Payloads bleibt netcat trotzdem der pragmatischste Einstieg, weil kein zusätzlicher Code geschrieben werden muss.

10. Zusammenfassung

Ein minimaler Webhook-Empfänger mit netcat löst ein sehr konkretes Problem: schnell und ohne Framework sehen, was ein Webhook-Absender tatsächlich sendet. Eine while-Schleife um nc -l nimmt Requests entgegen, eine feste oder parametrisierte HTTP-Response mit korrektem Statuscode, Content-Length und CRLF-Zeilenenden hält den Absender zufrieden, und awk extrahiert Header und Body sauber aus der aufgezeichneten Datei.

Für dauerhaftes Debugging über mehrere Tage macht ein systemd-Service den Empfänger robust gegen Abstürze. Wichtig bleibt die Grenze: Ein Webhook-Empfänger mit netcat gehört nie in die Produktion, weil Signaturprüfung, TLS und Parallelverarbeitung fehlen. Für schnelle lokale Analyse und für das Debugging von Drittanbieter-Integrationen ist er dennoch eines der nützlichsten Bash-Werkzeuge im Netzwerk-Alltag.

11. FAQ: Minimaler Webhook-Empfänger mit netcat