Developer docs

Send readable database change alerts from any app.

NotifyDB gives each project a bearer token and a single JSON endpoint. Post a change event when your app creates, updates, or deletes a record; NotifyDB handles notification timing, quotas, and optional summaries.

Endpoint POST /api/events

Auth Bearer ndb_...

Payload created | updated | deleted

Quickstart

Create a project, save its token, then choose database-native triggers or a direct HTTP call for your first event.

Create a project

Open the dashboard, create a project, and choose where notifications should go. Each project has its own token and notification settings.

Save the token

The full token is shown once. Store it in your server environment, not in browser JavaScript or a public repo.

Choose an integration

Use the database agent for PostgreSQL/MySQL, or send the same event payload from your application code.

Database-native setup

Install lightweight triggers in PostgreSQL or MySQL. Triggers write to a local outbox table; the NotifyDB agent forwards events without blocking your app's write path.

PostgreSQL

Set DATABASE_URL to a PostgreSQL connection string and list tables as public.users,public.orders.

MySQL

Set DATABASE_URL to a MySQL connection string and list tables as users,orders or app.users.

Install triggers

npm install -g notifydb-db-agent
notifydb-db-agent init

# edit .env.notifydb, then:
notifydb-db-agent install

Run the forwarder

NOTIFYDB_API_URL=https://notifydb.io \
NOTIFYDB_PROJECT_TOKEN=YOUR_PROJECT_TOKEN \
DATABASE_URL=postgresql://app:password@localhost:5432/app \
NOTIFYDB_TABLES=public.users,public.orders \
notifydb-db-agent run

Single-column primary keys only

The installer validates each watched table. Tables without a primary key or with composite primary keys are skipped with a clear error.

Outbox delivery

The agent retries failed sends and stores the last error in notifydb_outbox. Database writes do not wait for NotifyDB.

HTTP examples

Use cURL to prove the token works. Use the JavaScript example from a server route, worker, webhook handler, or API backend.

cURL

curl -X POST https://notifydb.io/api/events \
  -H "Authorization: Bearer YOUR_PROJECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tableName":"users","recordId":"42","eventType":"updated","oldValues":{"email":"old@example.com"},"newValues":{"email":"new@example.com"}}'

JavaScript

await fetch('https://notifydb.io/api/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.NOTIFYDB_TOKEN,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tableName: 'users',
    recordId: '42',
    eventType: 'updated',
    oldValues: { email: 'old@example.com' },
    newValues: { email: 'new@example.com' }
  })
});

Payload

The request body is intentionally small. Send the record identity, the change type, and the before/after values you want people to see.

Field	Type	Notes
`tableName`	string	The table, collection, model, or resource that changed.
`recordId`	string or integer	The ID your team would use to find the record again.
`eventType`	string	One of `created`, `updated`, or `deleted`.
`oldValues`	object	Values before the change. Use an empty object for creates.
`newValues`	object	Values after the change. Use an empty object for deletes.

Responses

A successful request means NotifyDB accepted the event. Notification delivery may still happen asynchronously depending on the project's frequency.

201 Created

{
  "id": 123,
  "createdAt": "2026-05-17T14:08:21+00:00",
  "humanSummary": "User ID 42 was updated: email changed."
}

Authentication errors

401 means the bearer token is missing or invalid. Regenerate the project token if the original token was lost.

Validation and quotas

422 means a payload field is missing or malformed. 429 means the weekly event limit has been reached.

Production notes

Keep the integration boring. NotifyDB should sit beside your existing write path without becoming a hard dependency for saving user data.

Use trusted infrastructure

Run the database agent beside your application or call NotifyDB from backend code. Do not expose project tokens in client-side JavaScript.

Send useful fields, not everything

Include the values a teammate would need to understand the change. Skip secrets, large blobs, and noisy internal metadata.

Do not block critical writes

If your app can queue background jobs, enqueue the NotifyDB call after the database write succeeds. If the call fails, retry it like any other outbound webhook.