feat: enhance webhooks

.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore

.gitattributes

@@ -0,0 +1,2 @@
+docker/Dockerfile text eol=lf
+docker/*.sh text eol=lf

.gitignore

@@ -164,3 +164,6 @@ cython_debug/
 .dev.env
 !.env.example
 certs
+
+# Git worktrees
+.worktrees/

.pre-commit-config.yaml

@@ -59,7 +59,9 @@ repos:
     hooks:
       - id: detect-secrets
         args: [
-          '--baseline', '.secrets.baseline',
+          '--exclude-files', 'docs',
+          '--exclude-files', 'migrations',
+          '--exclude-files', 'alembic.ini',
         ]
         exclude: package.lock.json
         stages: [ pre-commit, pre-merge-commit, manual ]

docker-compose.dev.yml

@@ -80,5 +80,22 @@ services:
       retries: 3
       start_period: 40s
 
+  fastid-webhook-worker:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile
+      target: dev
+    env_file: .env
+    entrypoint: ["poetry", "run", "python", "-m", "fastid.webhooks.worker"]
+    depends_on:
+      fastid-app:
+        condition: service_healthy
+    environment:
+      FASTID_DB_URL: ${FASTID_DB_URL:-postgresql+asyncpg://${POSTGRES_USER:-fastid}:${POSTGRES_PASSWORD:?database password required}@postgres:5432/${POSTGRES_DB:-fastid}}
+      FASTID_WEBHOOK_ALLOW_INSECURE_URLS: ${FASTID_WEBHOOK_ALLOW_INSECURE_URLS:-true}
+    volumes:
+      - "./fastid:/opt/fastid/fastid"
+    restart: unless-stopped
+
 volumes:
   pg_data:

docker-compose.prod.yml

@@ -4,3 +4,8 @@ services:
       context: .
       dockerfile: docker/Dockerfile
       target: prod
+  fastid-webhook-worker:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile
+      target: prod

docker-compose.yml

@@ -67,5 +67,18 @@ services:
       retries: 3
       start_period: 40s
 
+  fastid-webhook-worker:
+    env_file:
+      - .env
+    image: everysoftware/fastid:latest
+    entrypoint: ["python", "-m", "fastid.webhooks.worker"]
+    depends_on:
+      fastid-app:
+        condition: service_healthy
+    environment:
+      FASTID_DB_URL: ${FASTID_DB_URL:-postgresql+asyncpg://${POSTGRES_USER:-fastid}:${POSTGRES_PASSWORD:?database password required}@postgres:5432/${POSTGRES_DB:-fastid}}
+      FASTID_WEBHOOK_ALLOW_INSECURE_URLS: ${FASTID_WEBHOOK_ALLOW_INSECURE_URLS:-false}
+    restart: unless-stopped
+
 volumes:
   pg_data:

docs/adr/0001-use-standard-webhook-headers.md

@@ -0,0 +1,26 @@
+# ADR 0001: Use Only Standard Webhook Headers
+
+- Status: Accepted
+- Date: 2026-07-20
+
+## Context
+
+FastID sends both a legacy configurable `X-Webhook-*` signature protocol and the fixed Standard Webhooks protocol. The
+protocols use different identifiers, signed representations, and signature encodings. Consumers therefore have two
+ways to authenticate the same delivery, only one of which protects the exact transmitted bytes.
+
+## Decision
+
+FastID will send and support only `webhook-id`, `webhook-timestamp`, and `webhook-signature`. The signature will remain a
+versioned base64 HMAC-SHA256 over `webhook-id.webhook-timestamp.raw_body`.
+
+The legacy signing functions, verification function, configurable header names, and configurable signature algorithm
+will be removed.
+
+## Consequences
+
+- New examples and integrations have one authentication contract.
+- The stable Webhook ID is unambiguously the consumer idempotency key.
+- Verification authenticates the exact transmitted body.
+- Existing consumers of `X-Webhook-*` must migrate to Standard Webhooks headers.
+- Supporting a future signing change will require a new version in `webhook-signature`, not a second header family.

docs/adr/0002-provide-tiered-webhook-receiver-examples.md

@@ -0,0 +1,32 @@
+# ADR 0002: Provide Tiered Standalone Webhook Receiver Examples
+
+- Status: Accepted
+- Date: 2026-07-20
+
+## Context
+
+A minimal webhook receiver is useful for first success but omits production concerns. Adding storage abstractions and
+database setup to that same file would obscure the authentication flow. Making examples import shared implementation
+code would reduce duplication but make each example harder to copy into another service.
+
+## Decision
+
+FastID will provide three standalone FastAPI receiver applications:
+
+- a quick-start authentication example;
+- an advanced in-memory Webhook-ID idempotency reference;
+- an advanced SQLAlchemy Webhook-ID idempotency reference.
+
+Each application will independently implement Standard Webhooks verification using Python's standard library. Advanced
+examples will share the same conceptual claim, complete, and release lifecycle but will not import each other.
+The SQLAlchemy example will use SQLAlchemy's async APIs with `aiosqlite` supplied by an optional Poetry `examples`
+dependency group.
+
+## Consequences
+
+- New users can reach a working receiver without database setup.
+- Experienced users can compare volatile and durable idempotency boundaries.
+- Each file can be copied independently.
+- Signature-verification code is intentionally duplicated and must be changed consistently if the protocol evolves.
+- The in-memory example is not production-durable and must say so prominently.
+- The SQLAlchemy example introduces database concepts only in its dedicated file.

docs/docs/tutorial/webhooks.md

@@ -0,0 +1,89 @@
+# Webhooks
+
+FastID sends user lifecycle events to every active endpoint subscribed to the event type. Delivery is asynchronous,
+durable, and at least once: consumers must treat `webhook-id` as an idempotency key because a delivery can be repeated
+after a timeout or worker crash. Delivery order is not guaranteed.
+
+## Request format
+
+Each request is a JSON `POST` with Standard Webhooks headers:
+
+- `webhook-id`: Webhook ID, unchanged for retries of the same delivery.
+- `webhook-timestamp`: Unix timestamp for the delivery attempt.
+- `webhook-signature`: `v1,<base64 HMAC-SHA256>` signature.
+
+The signed value is the exact byte sequence `webhook-id.webhook-timestamp.raw_body`. Verify the raw request body before
+parsing JSON; parsing and serializing it again can change the bytes.
+
+```python
+from fastapi import FastAPI, Header, Request
+
+from fastid.security.webhooks import verify_standard_headers
+
+app = FastAPI()
+
+
+@app.post("/fastid-webhooks")
+async def receive(request: Request) -> dict[str, bool]:
+    body = await request.body()
+    if not verify_standard_headers(body, request.headers, "whsec_..."):
+        return {"accepted": False}
+    event = await request.json()
+    # Atomically record request.headers["webhook-id"] before applying side effects.
+    return {"accepted": True}
+```
+
+The payload contains a separate logical event ID that can be shared by deliveries to multiple endpoints:
+
+```json
+{
+  "event": {
+    "event_type": "user_registration",
+    "event_id": "019b...",
+    "timestamp": 1784293200
+  },
+  "data": {
+    "user": {
+      "id": "019b...",
+      "email": "person@example.com"
+    }
+  }
+}
+```
+
+User events that historically exposed user fields directly in `data` continue to include those fields during the
+compatibility period; use `data.user` in new consumers.
+
+## Receiver examples
+
+Runnable receivers are available for different integration stages:
+
+- [`webhook_quickstart.py`](../../../examples/webhook_quickstart.py) verifies a signature and logs the event. It does
+  not check timestamp freshness or provide replay protection and idempotency.
+- [`webhook_sqlalchemy.py`](../../../examples/webhook_advanced.py) persists atomic Webhook-ID claims with async
+  SQLAlchemy. Install its SQLite driver with `poetry install --with examples`.
+
+The in-memory example is a concurrency reference, not durable storage. Use the SQLAlchemy example or another shared
+persistent idempotency store before applying non-idempotent production side effects.
+
+## Delivery behavior
+
+A `2xx` response completes delivery. Other responses and network failures are retried with jittered exponential
+backoff for roughly three days. FastID respects `Retry-After` up to 24 hours, never follows redirects, disables an
+endpoint immediately after `410 Gone`, and disables it after all attempts are exhausted.
+
+The API transaction stores delivery records; a separate worker sends them:
+
+```console
+python -m fastid.webhooks.worker
+```
+
+Docker Compose starts this worker automatically. Its Prometheus metrics are exposed on port `9101` inside the Compose
+network. Delivery and attempt history is also visible in the FastID admin application.
+
+## Endpoint security
+
+Production endpoints must use HTTPS, contain no URL credentials, and resolve only to public IP addresses. FastID pins
+the validated address for the connection and does not follow redirects. Keep the worker in an egress-restricted network
+as defense in depth. Local HTTP and private-address endpoints require the explicit
+`FASTID_WEBHOOK_ALLOW_INSECURE_URLS=true` development setting.