How to Receive Plaid Webhooks in Laravel

Exclude webhook routes from CSRF + use getContent for raw bytes

Laravel is the dominant PHP framework for SaaS development in 2026. Out of the box, the VerifyCsrfToken middleware blocks any POST without a token — including webhooks. The fix is to exclude the webhook URI from CSRF and read $request->getContent() for the raw bytes that HMAC verification needs. This guide walks through the Laravel setup for Plaid webhooks end to end: capturing the raw body, verifying the signature, handling retries idempotently, and iterating locally without redeploying. Cross-reference the Plaid Webhooks overview for the event catalog and sample payload.

1. Set Up the Laravel Endpoint

The endpoint needs to do three things, in this order: read the raw body, verify the signature against those exact bytes, and only then parse the JSON for your business logic.

// app/Http/Middleware/VerifyCsrfToken.php — exclude webhook URIs
class VerifyCsrfToken extends Middleware
{
    protected $except = ['webhooks/*'];
}

// routes/web.php (or routes/api.php)
Route::post('/webhooks/{service}', [WebhookController::class, 'receive']);

// app/Http/Controllers/WebhookController.php
namespace App\Http\Controllers;

use Illuminate\Http\Request;

class WebhookController extends Controller
{
    public function receive(Request $request, string $service)
    {
        // IMPORTANT: getContent() returns the raw body BEFORE parsing.
        $rawBody = $request->getContent();
        $signature = $request->header('X-Signature-Header');

        // 1. Verify HMAC over $rawBody
        // 2. Parse JSON only after verification passes
        // 3. Process the event idempotently (use the event id as your key)

        $event = json_decode($rawBody, true);
        logger()->info('Verified webhook', ['type' => $event['type'] ?? null]);

        return response('ok', 200);
    }
}

2. Verify the Plaid Signature

PHP verification

// composer require firebase/php-jwt plaid/plaid-php
use Firebase\JWT\JWT;
use Firebase\JWT\JWK;

class WebhookController extends Controller
{
    public function plaid(Request $request)
    {
        $body = $request->getContent();
        $token = $request->header('Plaid-Verification', '');
        if (!$token) {
            abort(401);
        }

        // Inspect JWT header for kid.
        [$headerB64] = explode('.', $token);
        $header = json_decode(
            base64_decode(strtr($headerB64, '-_', '+/')),
            true,
        );
        if (($header['alg'] ?? null) !== 'ES256') {
            abort(401);
        }

        // Fetch JWK from Plaid (configure SDK separately).
        $plaid = new \Plaid\Client(/* ... */);
        $keyResp = $plaid->webhookVerificationKeyGet($header['kid']);

        $publicKey = JWK::parseKey($keyResp->key, 'ES256');
        $decoded = JWT::decode($token, $publicKey);

        if (abs(time() - ($decoded->iat ?? 0)) > 300) {
            abort(401);
        }

        $bodyHash = hash('sha256', $body);
        if (!hash_equals($bodyHash, $decoded->request_body_sha256 ?? '')) {
            abort(403);
        }
        return response()->json(['ok' => true]);
    }
}

Wire this verification call into the Laravel handler from section 1. The pattern is identical across Laravel versions: read raw body, verify, parse JSON, dispatch.

See Plaid's official signing docs for the canonical reference, or the cross-service signature verification guide for the same pattern in Ruby and other languages.

3. Make the Handler Idempotent

Plaid can — and will — send the same event twice. Network blips, your server returning a 5xx mid-processing, deploy windows: any of these triggers a retry, and your handler will see the same event id again. Build for that on day one rather than chasing duplicate-charge bugs in production.

The simplest pattern is a unique constraint on the event id in your database. The handler does the work inside a transaction, and the insert into the events table is the last step — if a retry arrives, the unique-constraint violation tells you the event already committed and you can return 200 without re-running the side effects.

4. Test Locally Without Deploying

The fastest iteration loop for any webhook handler is: capture a real Plaid event with HookRay, then replay that captured request against your local Laravel server until the verification + business logic both pass. No need to retrigger the event in Plaid, no need to redeploy.

1. Get a free webhook URL at hookray.com — no signup.
2. Paste the URL into your Plaiddashboard's webhook settings.
3. Trigger a test event. HookRay shows the headers, raw body, and parsed payload in real time.
4. Use HookRay's replay feature to send the captured request against http://localhost:3000/api/webhooks/plaid (or wherever your Laravel app is listening) — iterate on your code without re-poking the Plaid dashboard.

Deploying the Laravel Handler

Laravel runs comfortably on Forge/Vapor, traditional VPS (Render, DigitalOcean App Platform), and Docker containers. Octane (Swoole / RoadRunner) keeps boot warm for webhook traffic — at scale, an Octane worker handles incoming webhooks several times faster than per-request PHP-FPM. For low volume, classic LAMP / PHP-FPM is fine.

Need a host that boots quickly enough to absorb webhook bursts? DigitalOcean droplets stay warm, support raw-body proxies cleanly, and avoid the cold-start traps of some serverless runtimes.