Warum gibt Laravel 419 auf Webhook-POSTs zurück?

VerifyCsrfToken lehnt POSTs ohne gültiges CSRF-Token ab. Webhook-Pfad zu $except hinzufügen und stattdessen Signaturen prüfen.

getContent() oder all() für Webhooks?

Nutze getContent() für die Signaturprüfung. all() und input() liefern geparste Daten, nicht die signierten Bytes.

Wie teste ich Laravel-Webhooks lokal?

php artisan serve starten, mit npx portpreview exponieren, Tunnel-URL ins Dashboard einfügen und Test-Events auslösen.

Laravel-Webhooks: CSRF-Ausnahme, Raw Body, Signaturprüfung

Laravel schützt jede Web-Route per CSRF. Webhook-Anbieter senden POSTs ohne Session-Cookie oder CSRF-Token — Sie erhalten 419, bevor der Controller läuft. Fix: gezielte CSRF-Ausnahme plus Raw-Body mit $request->getContent().

CSRF für Webhook-Routen überspringen

Webhook-URI zum $except-Array in App\Http\Middleware\VerifyCsrfToken hinzufügen (Laravel 11+: Middleware in bootstrap/app.php):

protected $except = [
    'webhooks/stripe',
    'webhooks/*',
];

Ausnahmen eng fassen — nur server-to-server Webhook-Pfade, nie global CSRF abschalten.

Raw-Body für Signaturprüfung lesen

Nach CSRF-Bypass unveränderte Bytes lesen:

public function handle(Request $request)
{
    $payload = $request->getContent(); // raw string
    $signature = $request->header('Stripe-Signature', '');

    if (!$this->verifySignature($payload, $signature)) {
        return response('', 401);
    }

    $event = json_decode($payload, true, 512, JSON_THROW_ON_ERROR);
    $this->processEvent($event);
    return response('', 200);
}

getContent() nutzen, nicht all() oder input() — Laravels Helper liefern nicht die signierten Bytes.

Signaturen vor Business-Logik prüfen

Provider-Header extrahieren, Digest aus Raw-Payload berechnen, mit hash_equals vergleichen. Bei Mismatch 401. Siehe Leitfaden zur Signaturprüfung.

Tunnel einrichten

Laravel starten: php artisan serve --port=8000.
Zweites Terminal: npx portpreview 8000.
Tunnel-URL + Pfad ins Provider-Dashboard.
TrustProxies: Forwarded-Header vom Tunnel vertrauen.
Test-Event auslösen.

Häufige Stolperfallen

Body zweimal lesen

getContent() nach json() ist leer. Einmal lesen, speichern, prüfen, parsen.

Middleware-Reihenfolge

Globales JSON-Parsing vor dem Controller verändert Bytes. Webhook-Routen isolieren.

Retries und Idempotenz

Event-IDs persistieren — siehe Retry- und Idempotenz-Muster.

Weiterführend

Grundlagen finden Sie unter localhost-Tunneling-Grundlagen und praktisches lokales Webhook-Debugging. Zur Signaturmechanik siehe den Leitfaden zur Signaturprüfung. Für duplikatsichere Handler lesen Sie Retry- und Idempotenz-Muster. starten Sie PortPreview kostenlos.