How to Receive Plaid Webhooks in FastAPI

Read request.body() before any json() call

FastAPI is the modern Python web framework of choice for new projects in 2026. Pydantic-style request models are great for application APIs but actively get in the way of webhooks — you need the raw bytes the sender signed, not a parsed Pydantic object. This guide walks through the FastAPI 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 FastAPI 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.

# main.py
from fastapi import FastAPI, Request, HTTPException
import json

app = FastAPI()


@app.post("/api/webhooks/{service}")
async def webhook(service: str, request: Request):
    # IMPORTANT: read the raw body FIRST.
    # Once you call request.json() the body is consumed.
    raw_body = await request.body()
    signature = request.headers.get("x-signature-header", "")

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

    event = json.loads(raw_body)
    print("Verified webhook:", event.get("type") or event)

    return {"status": "ok"}

2. Verify the Plaid Signature

Python verification

# pip install python-jose plaid-python
import hashlib, os, time
from jose import jwt as jose_jwt
from plaid.api import plaid_api
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
plaid_client = plaid_api.PlaidApi(...)  # configured per Plaid SDK docs

@app.post("/webhooks/plaid")
async def plaid_webhook(request: Request):
    body = await request.body()
    token = request.headers.get('plaid-verification')
    if not token:
        raise HTTPException(status_code=401, detail='missing token')

    # 1. Inspect header to get kid + confirm ES256.
    header = jose_jwt.get_unverified_header(token)
    if header.get('alg') != 'ES256':
        raise HTTPException(status_code=401, detail='wrong alg')

    # 2. Fetch JWK from Plaid.
    resp = plaid_client.webhook_verification_key_get({'key_id': header['kid']})
    jwk = resp['key']

    # 3. Verify JWT (ES256) — python-jose accepts JWK dicts directly.
    claims = jose_jwt.decode(token, jwk, algorithms=['ES256'])

    # 4. Replay window + body hash check.
    if abs(int(time.time()) - claims.get('iat', 0)) > 60 * 5:
        raise HTTPException(status_code=401, detail='stale request')
    body_hash = hashlib.sha256(body).hexdigest()
    if body_hash != claims.get('request_body_sha256'):
        raise HTTPException(status_code=403, detail='body hash mismatch')
    return {'ok': True}

Wire this verification call into the FastAPI handler from section 1. The pattern is identical across FastAPI 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 FastAPI 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 FastAPI app is listening) — iterate on your code without re-poking the Plaid dashboard.

Deploying the FastAPI Handler

FastAPI is typically deployed behind Uvicorn or Gunicorn + Uvicorn workers. For webhook handlers specifically, ensure your reverse proxy (Nginx, Cloud Load Balancing, etc.) doesn't buffer or rewrite request bodies — some default configurations strip trailing whitespace or normalise charset, which silently breaks HMAC.

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.