Skip to main content
POST
Watch the columns of one table for data events

Authorizations

Authorization
string
header
required

WorkOS access JWT or a user-owned WorkOS API key. User keys are bound to one organization and restricted to their enabled product permissions. Session-only onboarding and session revocation require an interactive access JWT. No cookie session is assumed.

Headers

X-Request-Id
string

Optional caller-provided correlation identifier.

Required string length: 1 - 128
Idempotency-Key
string
required

Identifies one mutation and its canonical request payload.

Required string length: 1 - 128

Path Parameters

project_id
string
required

Project identifier.

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$

Body

application/json
environment
enum<string>
required
Available options:
dev,
prod
table
string
required

Ordinary table owned by the application, created by a deployed migration.

Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,62}$
columns
string[]
required

Columns published with every event, exactly as written; names are case-sensitive.

Required array length: 1 - 32 elements
Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,62}$
schema
string
default:public

Schema of the table, public when omitted. The schemas pgcf, ohmyhost, information_schema and pg_* cannot be watched.

Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,62}$
operations
enum<string>[]

Row changes that publish an event; all three when omitted.

Required array length: 1 - 3 elements
Available options:
insert,
update,
delete

Response

The watch with the event type its deliveries carry.

id
string
required
Pattern: ^pgcf_watch_[0-9a-f]{8}$
environment
enum<string>
required
Available options:
dev,
prod
schema
string
required
Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,62}$
table
string
required
Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,62}$
columns
string[]
required
Required array length: 1 - 32 elements
Pattern: ^[A-Za-z_][A-Za-z0-9_]{0,62}$
operations
enum<string>[]
required
Required array length: 1 - 3 elements
Available options:
insert,
update,
delete
topic
string
required

Topic of the watched table, derived by the platform from its name.

Pattern: ^[a-z][a-z0-9_]{0,47}$
event_type
string
required

Event type of the rows of the table; pass it to a database webhook.

Pattern: ^data\.[a-z][a-z0-9_]{0,47}$