Webhooks, integrations, and a real API surface

The shape of this release

CapyDB has been deliberately small: Postgres, previews, backups, restores, imports. This batch of work does not widen what the database does. It widens how the rest of your tooling talks to it.

Outbound webhooks

Organizations can register HTTPS endpoints and subscribe to lifecycle events: project.ready, preview.ready, backup.completed, restore.completed, import.completed, credentials.rotated, preview.deleted, project.deleted, and the catch-alls job.completed and job.failed.

Deliveries are signed (X-CapyDB-Signature, HMAC-SHA256 over a timestamped payload, secret shown once), retried with backoff up to eight attempts, and the delivery history is queryable when you need to know what happened at 3 a.m. The verification snippet is in the docs, and it is twelve lines, because it should be.

Polling GET /v1/jobs/{id} still works and remains the source of truth. Webhooks are the fast path, not a replacement for one.

Vercel and Netlify

Connect a token and CapyDB pushes DATABASE_URL (pooled) and DATABASE_URL_UNPOOLED (direct) into your project's environment — and keeps pushing after credential rotations, restores, and imports, which is the part manual env management always gets wrong eventually.

With preview branches enabled, every git branch gets a clone-mode preview database named after it, with branch-scoped env vars, cleaned up by TTL rather than by hoping a deletion hook fires. One honest caveat documented up front: the very first build of a brand-new branch can start before its env var lands. If you need strict ordering, the GitHub Action does database-then-build synchronously.

Clerk auth sync

If Clerk holds your users, CapyDB can now maintain a capydb_auth.users table inside your own database — backfilled, then kept fresh by a Clerk webhook. User emails become a JOIN instead of an API call. The table is plain Postgres in your schema; nothing proprietary to query through.

Project-scoped API keys

Keys can now be minted for a single project. They cannot touch sibling projects and org-management scopes are rejected outright. CI gets the key it needs and nothing else. The GitHub Action docs now tell you to use one, and you should.

Import preflight

capydb import preflight --source-url ... connects to the source and grades the import before anything destructive happens: size against your plan, Postgres major compatibility (no downgrades), extension availability against the allowlist. The worker re-runs the same checks before the import's destructive step, so the gate holds even if the source changed since you checked.

This also unblocked the thing people actually wanted it for: per-provider migration playbooks — Neon, Supabase, Railway, Render, Heroku, RDS, Fly — are now in the docs, including where each provider hides its connection string and which of its defaults will bite you.

The docs got rebuilt too

Sectioned navigation, search, framework connection guides, a generated API reference that cannot drift from the OpenAPI document, and a limits page with actual numbers in it. Same voice. The product surface is still small; it is just documented like we mean it.