FastAPI Webhooks

Proxy traffic to FastAPI and consume JSON webhooks securely behind your Relay gateway.

Overview

FastAPI is a high-performance Python framework perfect for building JSON APIs and handling webhooks. By placing Relay in front of your FastAPI service, Relay manages authentication, rate limiting, and observability. This allows your Python code to focus purely on business logic using standard Pydantic models.

Building the API

In a standard FastAPI() app, you can seamlessly validate incoming JSON payloads by defining Pydantic models. To ensure that incoming traffic is securely routed through your gateway (and not spoofed directly to your server), you can read the Request.headers for Relay-specific signatures, such as x-relay-signature.

Copyfrom fastapi import FastAPI, Request, HTTPException from pydantic import BaseModel app = FastAPI() class WebhookResponse(BaseModel): status: str message: str class WebhookPayload(BaseModel): event: str data: dict @app.post("/webhook", response_model=WebhookResponse) async def handle_webhook(payload: WebhookPayload, request: Request): # Verify the request came through Relay signature = request.headers.get("x-relay-signature") if not signature: raise HTTPException(status_code=401, detail="Missing Relay signature") # Process the payload securely return WebhookResponse(status="success", message="Webhook received")

Running with Uvicorn

Because Relay proxies requests to your backend, your FastAPI application runs behind a reverse proxy. To ensure FastAPI receives the correct client IP addresses and forwarded headers, you must configure Uvicorn to trust these forwarded IPs.

Use the --proxy-headers and --forwarded-allow-ips flags when starting your uvicorn server:

Copyuvicorn main:app --proxy-headers --forwarded-allow-ips="*"

For production deployments, we highly recommend restricting forwarded_allow_ips to Relay's specific egress IP addresses rather than allowing all IPs (*).