Webhook

GitHub -> Jenkins/CI.

1. Du sagst GitHub: "Wenn jemand pusht, rufe https://jenkins.com/hook an."
2. Du pushst Code.
3. GitHub sendet JSON Payload an Jenkins:

   { "pusher": "max", "commit": "a1b2c3", "branch": "main" }
   

4. Jenkins wacht auf und startet den Build.

Praxisroutine

In der Praxis lernst du Webhook, indem du mit einem kleinen, kontrollierten Beispiel beginnst. Baue zuerst einen Minimalfall, prüfe das Ergebnis, veraendere genau eine Sache und beobachte, was sich ändert. Notiere dir Eingabe, Aktion, Ausgabe und typischen Fehler.

Übung: Erstelle ein Beispiel aus deinem Alltag, fuehre den Ablauf gedanklich Schritt für Schritt durch und markiere die Stelle, an der du Feedback oder ein Log brauchst. Wenn du diese Stelle benennen kannst, verstehst du den Begriff praktisch.

1. Security (HMAC Signature)

Dein Webhook-Endpoint (/hook) ist öffentlich im Internet. Jeder Hacker kann Fake-Events senden ("Zahlung erfolgt"). Wie prüfst du, dass es wirklich Stripe/GitHub ist? HMAC Signatur. Der Sender hasht den Payload mit einem geheimen Schlüssel (sha256(json + secret)). Er sendet den Hash im Header: X-Hub-Signature: sha256=.... Du (Empfänger) hasht den Payload ebenfalls mit dem Secret. Stimmen die Hashes überein? Ja -> Authentisch. Nein -> Hacker (Drop!).

2. Retries & Idempotency

Dein Server ist down, als der Webhook kommt. Das Event geht verloren? Gute Anbieter (Stripe) versuchen es erneut (Exponential Backoff: nach 1h, 2h, 4h). Problem: Wenn dein Server langsam war und Stripe den Request 2x sendet... Führst du die Bestellung 2x aus? Nein! Nutze die Event-ID zur Deduplizierung (Idempotenz). "Habe ID evt_123 schon gesehen -> Ignorieren."

3. Local Development (Tunneling)

Webhooks funktionieren nicht auf localhost. GitHub kommt nicht durch deine FritzBox. Lösung: Tunneling. Tools: ngrok, localtunnel, cloudflared. Gibt dir temporär https://random.ngrok.io, das auf localhost:3000 weiterleitet. Perfekt zum Debuggen.

1. Fan-out Architektur (Asynchrone Verarbeitung)

Ein Webhook-Endpoint sollte niemals die eigentliche Arbeit erledigen. Wenn ein Webhook reinkommt, führt der Server eine Fan-out Strategie aus:

1. Der Endpoint validiert kurz die Signatur.
2. Er schreibt den Payload sofort in eine Message Queue (z. B. Redis, RabbitMQ oder AWS SQS).
3. Er sendet sofort 200 OK zurück an den Absender (Stripe/GitHub). Ein separater "Worker" nimmt den Job aus der Queue und verarbeitet ihn in Ruhe (z. B. PDF generieren). Das verhindert, dass der Absender in einen Timeout läuft und den Webhook als "fehlgeschlagen" markiert, nur weil dein Server gerade beschäftigt war.

2. Rate Limiting am Receiver

Was passiert, wenn GitHub dir 10.000 Webhooks in einer Sekunde sendet? Dein Server könnte an der Last ersticken (Self-Inflicted DDoS). Profis nutzen am Webhook-Endpoint ein Rate Limiting. Wenn zu viele Requests kommen, antwortet man mit 429 Too Many Requests. Gute Absender-Systeme verstehen das und probieren es später langsamer nochmal. So schützt du deine Infrastruktur vor unvorhersehbaren Event-Spitzen.

3. Mutual TLS (mTLS) & IP-Allowlisting

Für hochsensible Daten (Banken) reicht die HMAC-Signatur oft nicht aus. Man nutzt mTLS: Hier muss sich nicht nur der Server ausweisen (Zertifikat), sondern auch der Absender (Stripe) muss ein Client-Zertifikat vorlegen, das dein Server kennt. Zusätzlich nutzt man IP-Allowlisting. Du erlaubst den Zugriff auf /hook nur für die offiziellen IP-Adressen des Anbieters. Das macht es für Angreifer fast unmöglich, bösartige Daten einzuschleusen, selbst wenn sie deinen geheimen HMAC-Schlüssel gestohlen hätten.