Local development

Prerequisites

uv and Python 3.13.
GCP credentials with access to Secret Manager and Cloud Tasks.
A Cloud Tasks queue configured for the target project.

Required environment

export GCP_PROJECT_ID="..."
export CLOUD_TASKS_SERVICE_ACCOUNT="..."
export CLOUD_TASKS_LOCATION="..."
export CLOUD_TASKS_QUEUE_ID="nest-data-handler"
export HANDLER_SERVICE_BASE_URL="https://<handler-cloud-run-url>"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

The service reads WEBHOOKS_API_KEY from Secret Manager. For local curl testing, fetch the secret value and export it in your shell.

HANDLER_SERVICE_BASE_URL should point at the default Cloud Run URL for the internal Handler service.

Install dependencies

# From repo root
uv sync --all-packages

Run locally

# From repo root
uv run --package webhooks granian --interface asgi services.webhooks.main:app --host 0.0.0.0 --port 8080 --workers 1 --loop uvloop

Sanity checks

curl http://localhost:8080/api/v1/health

Example request

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $WEBHOOKS_API_KEY" \
  -H "Idempotency-Key: 11111111-1111-1111-1111-111111111111" \
  -H "X-Organization-Id: ORG_ID" \
  -d '{"invoices": []}' \
  http://localhost:8080/api/v1/invoices

Tests

# From repo root
uv run --package webhooks pytest -q