# Add a Database Webhook to a Supabase App

Yes. An agent adds a migration with a pg_net trigger that posts row changes to your server, a Next.js route that verifies them, a pgTAP test, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-database-webhooks/supabase/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the schema and the app before writing a trigger. In a project like Razikus/supabase-nextjs-template, `supabase/config.toml` runs the local stack with the API on 54321, the database on 54322, Studio on 54323, storage, realtime and the edge runtime enabled, and MFA with TOTP enrol and verify on. Four migrations under `supabase/migrations/` create an `authenticative.is_user_authenticated()` function that requires `aal2` once a verified MFA factor exists, an example storage bucket with its policies, and `public.todo_list`: an identity `id`, `created_at`, `title`, `urgent`, `description`, `done`, `done_at` and an `owner` uuid with a cascading foreign key to `auth.users`, row level security on, grants to `anon`, `authenticated` and `service_role`, and one policy, "Owner can do everything", for authenticated users whose `owner` is `auth.uid()`. The Next.js 15 app under `nextjs/` uses `@supabase/ssr` and `supabase-js` 2.47 through a `SassClient` wrapper in `src/lib/supabase/unified.ts`, with server, browser and admin clients beside it; its only API route is `src/app/api/auth/callback/route.ts`, and the todo UI lives under `src/app/app/table`. No migration enables `pg_net`, no `functions` block is configured, and nothing outside the database learns when a todo changes.

It writes one migration, `supabase/migrations/<timestamp>_todo_webhook.sql`. It enables `pg_net` in the `extensions` schema, creates `public.todo_events` (`id`, `todo_id`, `event`, `payload jsonb`, `delivered_at`, `response_status`) granted to `service_role` only, and defines `public.notify_todo_webhook()` as a `security definer` function with `set search_path = ''`, which reads `webhook_url` and `webhook_secret` from `vault.decrypted_secrets` by name, builds a JSON body of `type` (`INSERT` or `UPDATE`), `table`, `record` and `old_record`, calls `net.http_post` with a `Content-Type` and an `Authorization: Bearer` header and a five-second timeout, and inserts the request id into `todo_events`. A trigger `todo_list_webhook` fires `after insert or update of done on public.todo_list for each row`, so ticking a todo sends one request and editing its title sends none. The two Vault secrets are created in the migration only if absent, with placeholder values a `supabase secrets`-style note in the pull request tells the reader to replace, since a URL and a bearer token do not belong in Git.

The receiving side is `nextjs/src/app/api/webhooks/todo/route.ts`: a `POST` handler that reads the raw body, compares the bearer token to `TODO_WEBHOOK_SECRET` from the environment with a constant-time comparison, parses the payload, and records the delivery by updating `todo_events` through the existing admin client in `serverAdminClient.ts`, which is what makes the loop observable from the app. The handler returns `204` on success and `401` on a bad token, and the agent adds the variable to `.env.template`, regenerates `src/lib/types.ts` with `supabase gen types` so `todo_events` is typed, and leaves the todo page alone.

The sandbox has no Docker, which the Supabase CLI needs, so the agent installs it, starts `dockerd`, runs `supabase start` and `supabase db reset` to apply all five migrations from scratch, and runs `supabase db lint` on the new function. It writes `supabase/tests/todo_webhook.test.sql` in pgTAP, checking that the trigger exists on `todo_list` with the right events, that the function is `security definer` with an empty search path, that `todo_events` is not readable by `authenticated`, and that inserting a row as a test user enqueues exactly one `net.http_request_queue` entry; `supabase test db` runs it. In `nextjs/`, `next build` type-checks the new route against the regenerated types and `next lint` passes. No request reaches a real server from the sandbox, and the pull request says so.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a database webhook to this Supabase app so my server is notified when a todo is created or marked done. Read supabase/config.toml, every migration, the Next.js app's supabase client files, its API routes and its env template first. Write one migration that enables pg_net, creates a todo_events table readable only by service_role, defines a security definer trigger function with an empty search_path that reads the webhook URL and secret from Vault, posts type, table, record and old_record as JSON with a bearer Authorization header and a short timeout, and records the request; attach it as an after insert or update of done trigger on todo_list. Create the Vault secrets only if absent with placeholder values and say in the pull request how to set the real ones. Add a Next.js route handler that verifies the bearer token in constant time, marks the delivery in todo_events through the admin client, and returns 204 or 401; add the secret to the env template and regenerate the database types. Install Docker, start the local stack, reset the database to apply every migration, lint it, write a pgTAP test for the trigger, the function's security settings, the table's grants and the queued request, and run it. Build and lint the Next.js app. Open a pull request that says no delivery to a real server was made.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that adds one migration, `supabase/tests/todo_webhook.test.sql` and `nextjs/src/app/api/webhooks/todo/route.ts`, and edits `nextjs/src/lib/types.ts` and `.env.template`. The description explains the trigger's events and the body it sends, names the two Vault secrets and the one environment variable, and gives the two commands to set the real URL and token after deploy.

The run's record keeps the `supabase db reset` output with all five migrations applied, the lint result, the pgTAP run with each assertion named, and the `next build` and `next lint` output, so a reviewer sees the function, trigger and grants are what the description says and that the route compiles against the regenerated types. The pull request says plainly that no request left the sandbox.

Before merging, a reviewer deploys the migration to a staging project, sets the Vault secrets to the staging app's URL and a fresh token, sets the same token in the app's environment, ticks a todo in the UI, and reads `todo_events`: one row with the request id and, once the route has answered, a `204` in `response_status`. A wrong token shows as `401` in the same column.

## Run it on every GitHub issue labelled agent

A team that tracks backend work in GitHub issues adds an automation with a `github` trigger on `issues.labeled` for the label `agent`, the Project that has this repository, and this prompt. Labelling the issue that asks for notifications on todo changes starts one run with the issue's text after the prompt, and the pull request links back to the issue. Only a label applied by an owner, member or collaborator fires it.

The trigger fills in no placeholder, so the issue says which table and which events, and the same automation serves the next one, such as a webhook on storage uploads, with the agent reading the migrations fresh each time.

## Why run it on Rush?

A database webhook is a trigger, a function with the right security settings, two secrets that must not be committed, a table to make deliveries visible, a receiving route, and a type regeneration, and the dangerous mistakes are in the function's `search_path` and the grants on the events table. The agent reads the real migrations in its own sandbox, applies them from scratch with the local stack, and proves the security properties with pgTAP before a reviewer reads the SQL.

Every command and its output stay in the run's record, and the pull request separates what was verified locally from the one thing only a deployed project can show: a real delivery to a real URL.

## Frequently asked questions

### Why pg_net in a migration rather than a webhook in the dashboard?

The dashboard creates the same kind of trigger, but outside Git, so a `db reset` or a new project loses it. A migration with the trigger, the function and the events table is reviewed, applied to every environment the same way, and testable with pgTAP.

### Where do the URL and token live?

In Supabase Vault, read by the function at call time, and in the app's environment for the receiving route. The migration creates the two secrets with placeholders only if they do not exist; the pull request gives the commands to set the real values in each environment.

### What if my server is down when a todo changes?

`pg_net` sends the request asynchronously and records the response in its own tables; the todo update itself never waits or fails. The `todo_events` row keeps the request id, and a `response_status` that never arrives or is a 5xx is the signal to replay from that table.

### Why only insert and done, not every update?

The trigger is `after insert or update of done`, so editing a title or description sends nothing. That matches the question asked and keeps the volume low; widening it is a one-line change to the trigger's column list.

### Does the agent send a real webhook?

No. The sandbox applies the migrations on the local stack and shows with pgTAP that an insert enqueues exactly one request, but no server is listening and nothing leaves the sandbox. The staging deploy with real secrets is the first delivery, and the pull request says so.

## More Supabase jobs

- [Add an Edge Function to a Supabase Project](https://getrush.ai/run/add-edge-function/supabase/)
- [Add Full-Text Search to a Supabase App](https://getrush.ai/run/add-full-text-search/supabase/)
- [Set Up GitHub Actions CI for a Supabase Project](https://getrush.ai/run/add-github-actions-ci/supabase/)

## More jobs like this: Turn a Linear label into a PR

- [Add Deep Link Handling to an Electron App from a Linear Issue](https://getrush.ai/run/add-deep-links/electron/)
- [Add Deferrable Operators to an Airflow Project](https://getrush.ai/run/add-deferrable-operators/airflow/)
- [Add a Dev Container to a .NET Solution](https://getrush.ai/run/add-dev-containers/dotnet/)

## Keep reading

- [What an agent can do in Supabase itself, once you connect it](https://getrush.ai/integrations/supabase/)
- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
