Paystack Webhook Returning 419 in Laravel

You set up a Laravel route for your Paystack webhook. You configure the URL in the Paystack dashboard. A transaction happens. Paystack sends the webhook. Your Laravel app returns:

HTTP/1.1 419
Content-Type: application/json

{
  "message": "CSRF token mismatch."
}

Or in your Laravel logs:

Symfony\Component\HttpKernel\Exception\HttpException
419 | CSRF token mismatch.

Paystack sees the 419 response, marks the delivery as failed, and schedules a retry. The retry also fails with 419. After enough retries, Paystack gives up on your endpoint.

This happens because Laravel's VerifyCsrfToken middleware runs on all POST requests by default. It checks for a _token field in the request body or an X-CSRF-TOKEN header. Paystack sends neither.

CSRF (Cross-Site Request Forgery) protection exists to prevent malicious websites from making requests on behalf of your logged-in users. It works by requiring a secret token that only your frontend knows.

The flow for normal form submissions:

1. Laravel generates a CSRF token and embeds it in your form
2. User submits the form with the token
3. Laravel's VerifyCsrfToken middleware checks the token
4. If valid, the request proceeds. If missing or invalid, Laravel returns 419.

Webhooks are server-to-server requests. Paystack's server does not have access to your CSRF token. It cannot include one. So the middleware rejects every webhook request.

This is not a security flaw. CSRF protection and webhook authentication are two different security mechanisms for two different threat models. CSRF protects against browser-based attacks. Webhook signature verification protects against forged server-to-server requests.

Laravel 11 changed how middleware is configured. There is no longer a dedicated VerifyCsrfToken middleware class in your app by default. Instead, configure exclusions in bootstrap/app.php:

<?php

// bootstrap/app.php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->validateCsrfTokens(except: [
            'webhooks/paystack',    // exclude this route from CSRF
            // 'webhooks/*',        // or exclude all webhook routes
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })
    ->create();

The validateCsrfTokens(except: [...]) method tells Laravel to skip CSRF verification for the listed URIs. The path should match your route definition without a leading slash.

In Laravel 10, 9, 8, and older versions, add the webhook URI to the $except array in app/Http/Middleware/VerifyCsrfToken.php:

<?php

namespace App\Http\Middleware;

use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;

class VerifyCsrfToken extends Middleware
{
    /**
     * The URIs that should be excluded from CSRF verification.
     *
     * @var array<int, string>
     */
    protected $except = [
        'webhooks/paystack',
        // 'webhooks/*',  // wildcard if you have multiple webhook providers
    ];
}

Make sure the URI in the $except array matches your route exactly. It is relative to the application root, without a leading slash. If your route is /webhooks/paystack, use 'webhooks/paystack' in the array.

You can use wildcards: 'webhooks/*' excludes all routes under /webhooks/. This is convenient if you also handle Stripe, Flutterwave, or other webhooks.

Here is a complete webhook controller with CSRF exclusion and signature verification:

Route definition (routes/web.php):

use App\Http\Controllers\PaystackWebhookController;

Route::post('/webhooks/paystack', [PaystackWebhookController::class, 'handle']);

Controller:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class PaystackWebhookController extends Controller
{
    public function handle(Request $request)
    {
        // Step 1: Get the raw body for signature verification
        $rawBody = file_get_contents('php://input');

        // Step 2: Get the signature header
        $signature = $request->header('X-Paystack-Signature');

        if (!$signature) {
            Log::warning('Paystack webhook: No signature header');
            return response('No signature', 401);
        }

        // Step 3: Verify the signature
        $secret = config('services.paystack.secret_key');
        $computed = hash_hmac('sha512', $rawBody, $secret);

        if (!hash_equals($computed, $signature)) {
            Log::warning('Paystack webhook: Signature verification failed');
            return response('Invalid signature', 401);
        }

        // Step 4: Parse the verified payload
        $event = json_decode($rawBody, true);

        // Step 5: Handle the event
        Log::info('Paystack webhook received: ' . $event['event']);

        match ($event['event']) {
            'charge.success' => $this->handleChargeSuccess($event['data']),
            'transfer.success' => $this->handleTransferSuccess($event['data']),
            'transfer.failed' => $this->handleTransferFailed($event['data']),
            default => Log::info('Unhandled Paystack event: ' . $event['event']),
        };

        // Step 6: Return 200
        return response('OK', 200);
    }

    private function handleChargeSuccess(array $data): void
    {
        Log::info('Processing charge.success: ' . $data['reference']);
        // Update your database, grant access, send receipts, etc.
    }

    private function handleTransferSuccess(array $data): void
    {
        Log::info('Processing transfer.success: ' . $data['reference']);
    }

    private function handleTransferFailed(array $data): void
    {
        Log::warning('Processing transfer.failed: ' . $data['reference']);
    }
}

Config (config/services.php):

'paystack' => [
    'secret_key' => env('PAYSTACK_SECRET_KEY'),
    'public_key' => env('PAYSTACK_PUBLIC_KEY'),
],

Laravel API routes (routes/api.php) do not have CSRF protection by default. If you define your webhook route in routes/api.php instead of routes/web.php, you do not need to exclude it from CSRF verification.

// routes/api.php
use App\Http\Controllers\PaystackWebhookController;

Route::post('/webhooks/paystack', [PaystackWebhookController::class, 'handle']);

The URL becomes /api/webhooks/paystack (prefixed with /api). Update the webhook URL in your Paystack dashboard to match.

This approach works but has trade-offs:

• Pro: No CSRF configuration needed.
• Con: API routes may have other middleware (like throttling or Sanctum auth) that you need to remove for the webhook route.
• Con: The /api prefix changes your URL. If you already configured the non-api URL in Paystack, you need to update it.

Most Laravel developers define webhook routes in routes/web.php with the CSRF exclusion. It is the more common pattern.

After applying the fix, verify it works:

# Test locally with artisan serve
php artisan serve

# In another terminal, send a test request
SECRET="sk_test_your_test_key"
BODY='{"event":"charge.success","data":{"id":12345,"reference":"test_ref","amount":50000,"currency":"NGN","status":"success"}}'
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$SECRET" | awk '{print $2}')

curl -X POST http://localhost:8000/webhooks/paystack \
  -H "Content-Type: application/json" \
  -H "X-Paystack-Signature: $SIGNATURE" \
  -d "$BODY"

# Expected: HTTP 200, body "OK"
# If you still get 419, the CSRF exclusion is not applied correctly

After deploying, trigger a test transaction from the Paystack dashboard and check your Laravel log file (storage/logs/laravel.log) for the webhook receipt log message.

For the complete error reference, see Paystack Errors and Troubleshooting: The Complete Reference. For signature verification details, see Paystack Signature Verification Failed: The Definitive Fix.

When starting a new Laravel project with Paystack integration:

1. Create a dedicated webhooks route group in your routes file from day one
2. Add the CSRF exclusion immediately, before you even build the handler
3. Use a naming convention that makes webhook routes obvious: /webhooks/paystack, /webhooks/stripe, etc.
4. Write a feature test that sends a POST to your webhook route without a CSRF token and asserts it does not return 419

// tests/Feature/PaystackWebhookTest.php
public function test_webhook_does_not_return_419(): void
{
    $response = $this->postJson('/webhooks/paystack', [
        'event' => 'charge.success',
        'data' => ['reference' => 'test_001'],
    ]);

    // Should be 401 (no valid signature) but NOT 419 (CSRF rejection)
    $this->assertNotEquals(419, $response->status());
}

This test catches the CSRF issue immediately if someone accidentally removes the exclusion.