Локальное тестирование вебхуков FastAPI: Request.body, подписи и async-безопасность

FastAPI makes webhook endpoints easy to write, but easy is not the same as safe. The critical details are reading raw bytes exactly once, verifying provider signatures before parsing, and structuring async handlers so slow tasks do not trigger retries.

Read raw bytes with Request.body()

In FastAPI, call await request.body() to get the exact incoming payload bytes for signature verification. Avoid parsing JSON first if your provider signs raw payloads. Verification must be done against untouched bytes.

Signature verification flow

Extract provider headers, build the signed payload string expected by that provider, compute HMAC or asymmetric validation, and return 401 on mismatch. Keep verification deterministic and close to route entry so failures are obvious in logs.

raw_body = await request.body()
expected = compute_signature(secret, timestamp, raw_body)
if not timing_safe_compare(expected, signature_header):
    raise HTTPException(status_code=401, detail='invalid signature')

Design async handlers for quick acknowledgements

Webhook providers expect fast 2xx responses. In FastAPI, acknowledge quickly, then offload expensive work to a queue, background worker, or task system. This reduces retry storms and keeps latency stable under traffic spikes.

Local tunnel workflow for realistic tests

Run your FastAPI app locally (Uvicorn or Hypercorn).
Expose the port with npx portpreview 8000.
Set provider webhook URLs to the generated HTTPS endpoint.
Trigger test events and inspect headers, body, and response timing.
Replay the same event ID to confirm idempotent behavior.

Idempotency is non-negotiable

Even perfectly verified requests can be delivered more than once. Use durable deduplication keys, transactional writes, and safe side-effect guards so duplicate deliveries do not create duplicate invoices, emails, or state transitions.