Architecture

Webhooks is a Python 3.13 FastAPI ingress service that validates incoming payloads and schedules Cloud Tasks for downstream processing.

System context

Partners/Bubble ---> Webhooks (FastAPI) ---> Cloud Tasks ---> Handler service (internal)
                         |-> Secret Manager (API key, Sentry DSN)
                         |-> Sentry (errors + traces)

Request flow

1. Client sends a request with X-API-Key and required headers.
2. APIKeyMiddleware validates the API key (health is exempt).
3. Endpoint validates request payload and size limits.
4. WebhookTaskScheduler enqueues a Cloud Task to Handler.
5. Response returns task metadata with 202 Accepted.

Bubble sync flow

• Bubble triggers send RawEvent payloads to /api/v1/nest-bub.
• Webhooks schedules a task to Handler /api/v1/webhooks/nest-bub.
• The task ID is derived from the event id for idempotency.

Components

• services/webhooks/main.py: app setup, middleware, logging, Sentry.
• services/webhooks/routers/: API routing.
• services/webhooks/api/v1/endpoints/: webhook endpoints.
• services/webhooks/core/cloud_tasks_scheduler.py: task creation and idempotency.
• services/webhooks/core/cloud_tasks_inspector.py: task status lookup.
• services/webhooks/middleware/api_key_middleware.py: API key enforcement.
• packages/python/common/: Secret Manager utilities.

Reliability and scaling

• Tasks are idempotent by design (task ids derived from request identifiers).
• Payload size is capped (750 KiB) to stay under Cloud Tasks limits.
• The service is stateless and scales horizontally.