send.otp / user.created, which are not infrastructure events), so Kestrel polls the Neon API on a per-tenant cadence to detect branch creation/readiness, operation failures, compute suspend/resume, and usage thresholds.
Prerequisites
- Organization Admin role in Kestrel
- A Neon account with at least one project
- A Neon API key (personal or organization) created in the Neon Console
- Your Neon Organization ID if your account is organization-scoped (found in the Console URL,
console.neon.tech/app/org-.../projects, or under Organization settings)
Setup
1
Create an API key
In the Neon Console (
console.neon.tech), open Account settings → API keys, click Create new API key, give it a name (e.g. kestrel), and copy the generated key (shown only once).The key is sent as a bearer token to the Neon API at console.neon.tech/api/v2 to read and manage projects, branches, compute endpoints, and operations. A personal key covers all projects you can access; an organization key scopes to that organization.2
Connect in Kestrel
- Navigate to Integrations → Neon in your Kestrel dashboard.
- Paste your API key.
- Enter your Organization ID if your Neon account is organization-scoped (a personal account can leave this blank). Find your org ID in the Neon Console URL when you open the org (
console.neon.tech/app/org-.../projects), or under Organization settings → Settings. - Choose a Poll Interval (how often Kestrel checks the Neon API for branch/compute/operation/usage events).
- Click Connect Neon — your Neon organization appears as connected.
All Neon triggers are detected by polling, so there may be up to one poll interval of delay before a workflow fires. The minimum poll interval is 60 seconds.
How It’s Used
In Workflows
Trigger blocks (all poll-based):- Branch Created — fires when a new Neon branch is created
- Branch Ready — fires when a branch becomes ready to connect
- Operation Failed — fires when a Neon operation (create branch, start compute, etc.) enters a failed state
- Compute Suspended — fires when a compute endpoint autosuspends to idle (cost signal)
- Compute Active — fires when a compute endpoint resumes to active
- Usage/Quota Threshold — fires when a project crosses a storage or compute usage threshold
- List Projects / Get Project, List Branches / Get Branch — inventory
- Create Branch — instant copy-on-write branch (optionally with a compute endpoint), ideal for ephemeral PR preview databases
- Delete Branch — tear down a branch (gate behind an Approval node)
- Reset Branch from Parent — the “reset my preview DB” action (gate behind an Approval node)
- List Compute Endpoints / Create Compute Endpoint / Delete Compute Endpoint
- Suspend Compute / Start Compute — cut/restore compute cost
- Set Autoscaling Limits — update a compute endpoint’s autoscaling min/max compute units
- Rotate Role Credentials — reset a role’s password and return a fresh connection URI (gate behind an Approval node)
- Get Connection URI — fetch a branch’s connection string (for posting to Slack)
- Investigate Neon — run an AI investigation of projects, branches, compute endpoints, and failed operations
{{signal.project_id}}, {{signal.branch_id}}, and {{signal.endpoint_id}} from the trigger.
Example (the flagship Neon flow): When a pull request opens, create a Neon copy-on-write preview branch and post the connection URI to Slack; when the PR closes, delete the branch.
Example (cost): When a compute endpoint suspends, notify the team; or on idle detection, suspend the compute to cut cost.
Example (dev requests): A “reset my preview DB” Slack request gates behind an Approval, then resets the branch from its parent.
Disconnecting
- Navigate to Integrations → Neon
- Click Disconnect
- Confirm the disconnection