Was Ist ein Webhook und Wie Integriert Man Ihn?

Die kürzeste Antwort auf die Frage "Was ist ein Webhook" lautet: Wenn in einem System ein Ereignis eintritt, sendet dieses System automatisch eine HTTP-Anfrage an eine URL, die du festlegst. Statt also ständig zu fragen "Ist etwas Neues passiert?", ruft dich die Gegenseite genau in dem Moment an, in dem das Ereignis eintritt. Diese kleine Umkehrung bildet das Rückgrat moderner Integrationen: Zahlungsanbieter, Git-Plattformen, Discord, E-Mail-Dienste und nahezu jedes SaaS-Produkt setzen auf Webhooks.

Der Unterschied zwischen Polling und Webhooks

Im Polling-Modell ruft deine Anwendung in regelmäßigen Abständen die entfernte API auf und fragt "Hat sich etwas geändert?". Meistens lautet die Antwort "nein", sodass der Großteil deiner Anfragen verschwendet ist. Selbst wenn du jede Minute fragst, entsteht eine durchschnittliche Verzögerung von 30 Sekunden zwischen dem Ereignis und dem Moment, in dem du davon erfährst.

Mit dem Webhook-Modell arbeitest du ereignisgesteuert: Sobald sich etwas ändert, pusht die Gegenseite die Daten sofort an deinen Endpoint. Die Vorteile sind eindeutig:

• Echtzeit: Du erfährst von einem Ereignis in dem Augenblick, in dem es passiert — die Latenz liegt im Millisekunden-, nicht im Sekundenbereich.
• Effizienz: Statt Tausender verschwendeter Anfragen wird nur für echte Ereignisse Datenverkehr erzeugt.
• Skalierbarkeit: Dein Server wird nicht durch überflüssige Abfragen belastet und du läufst nicht in Rate Limits.

Polling hat weiterhin seine Berechtigung: wenn die Gegenseite keine Webhooks anbietet oder wenn eine garantierte Zustellung zwingend erforderlich ist. Aber wenn du die Wahl hast, ist der ereignisgesteuerte Ansatz fast immer sauberer.

Wie sieht eine Webhook-Anfrage aus?

Eine Webhook-Anfrage ist eigentlich nur eine ganz gewöhnliche HTTP-POST-Anfrage. Das sendende System überträgt die Details des Ereignisses, meist in einem JSON-Body. Eine Zahlungsbestätigung könnte zum Beispiel so aussehen:

POST /webhooks/payment HTTP/1.1
Host: deine-seite.de
Content-Type: application/json
X-Signature: t=1719500000,v1=4a9f...c2

{
  "event": "payment.succeeded",
  "data": {
    "id": "pay_8sK2",
    "amount": 4900,
    "currency": "EUR",
    "customer": "cus_12"
  }
}

Deine Seite empfängt diese Anfrage, liest den Body, erledigt je nach event-Typ eine Aufgabe (bestätigt die Bestellung, sendet eine E-Mail, vergibt dem Nutzer eine Rolle) und gibt der Gegenseite schnell 200 OK zurück. Der entscheidende Punkt hier: Antworte schnell. Schiebe schwere Arbeit (Berichte erzeugen, externe APIs aufrufen) in eine Warteschlange; lass den Webhook nicht warten.

Einen Webhook-Empfänger mit Laravel bauen

In der Praxis ist das Schreiben eines Webhook-Endpoints sehr einfach. Mit Laravel genügen eine Route und ein Controller:

// routes/web.php
Route::post('/webhooks/payment', [WebhookController::class, 'handle'])
    ->withoutMiddleware([VerifyCsrfToken::class]);

Achtung: Webhooks kommen von externen Systemen und tragen kein Sitzungs-Cookie; deshalb musst du den CSRF-Schutz für diese Route ausschließen. Im Controller verarbeiten wir das Ereignis:

public function handle(Request $request)
{
    $payload = $request->all();

    if ($payload['event'] === 'payment.succeeded') {
        ProcessPayment::dispatch($payload['data']);
    }

    return response()->json(['ok' => true]);
}

Hier übergeben wir die Arbeit mit ProcessPayment::dispatch(...) an einen Queue-Job, sodass der Controller sofort antwortet und die schwere Arbeit im Hintergrund läuft.

Signaturprüfung: das Herz der Webhook-Sicherheit

Da deine Webhook-URL öffentlich erreichbar ist, musst du verhindern, dass ein böswilliger Akteur gefälschte Anfragen sendet. Die meisten Anbieter signieren den Body mit einem gemeinsamen Geheimnis per HMAC und senden die Signatur in einem Header (z. B. X-Signature). Du berechnest die Signatur mit demselben Schlüssel neu und vergleichst:

$signature = $request->header('X-Signature');
$expected  = hash_hmac('sha256', $request->getContent(), $secret);

if (! hash_equals($expected, $signature)) {
    abort(403, 'Ungültige Signatur');
}

Entscheidendes Detail: Berechne die Signatur über den rohen Body (getContent()), nicht über das geparste Array, denn das erneute Serialisieren des JSON kann Unterschiede auf Byte-Ebene erzeugen. Verwende außerdem hash_equals(), da == anfällig für Timing-Angriffe ist.

Zuverlässigkeit: Wiederholungen und Idempotenz

In der realen Welt läuft nicht immer alles glatt. Wenn dein Server einen Moment lang nicht antworten kann, wiederholen die meisten Anbieter die Anfrage. Das bedeutet, dass dasselbe Ereignis mehrfach eintreffen kann. Deine Handler müssen daher idempotent sein:

• Jedes Ereignis hat ein eindeutiges id-Feld; speichere es.
• Trifft dieselbe id erneut ein, mache die Arbeit nicht noch einmal — gib einfach 200 zurück.
• Gib schnell ein 2xx zurück; eine langsame Antwort führt dazu, dass der Anbieter dich als fehlgeschlagen einstuft und unnötig erneut versucht.

Um Webhooks während der Entwicklung zu testen, kannst du deinen lokalen Server mit einem Tunnel-Tool wie ngrok nach außen öffnen und Testereignisse aus dem Dashboard des Anbieters auslösen.

Häufige Fragen

Was ist der Unterschied zwischen einem Webhook und einer API?

Eine API ist meist ein "Pull"-Modell, bei dem du die Anfrage startest: Du fragst, du bekommst eine Antwort. Ein Webhook ist ein "Push"-Modell: Wenn ein Ereignis eintritt, sendet dir die Gegenseite Daten. Die meisten Integrationen nutzen beides zusammen.

Wie halte ich meine Webhook-URL sicher?

Verwende immer HTTPS, prüfe die Signatur jeder eingehenden Anfrage, setze nach Möglichkeit den IP-Bereich des Anbieters auf eine Allowlist und bewahre das Geheimnis in einer Umgebungsvariablen (.env) statt im Code auf.

Was tue ich, wenn ein Webhook nicht ankommt?

Sieh zuerst in den Zustellprotokollen des Anbieters nach; die meisten zeigen fehlgeschlagene Versuche und den zurückgegebenen HTTP-Code. Stelle sicher, dass dein Endpoint tatsächlich 200 zurückgibt, indem du den rohen Body protokollierst, und sende das Ereignis bei Bedarf manuell aus dem Dashboard erneut.

Brauchst du eine ereignisgesteuerte Integration? Ich helfe dir, sichere Webhook-Abläufe für Zahlungen, Discord, Git oder deine eigenen Systeme aufzubauen. Kontaktiere mich und lass uns über dein Projekt sprechen.