Insert webhook events into Postgres

The Postgres connector writes Novu webhook events to a table in your Postgres database. Use it when notification events need to live in an operational database or feed a reporting pipeline that already reads from Postgres. Novu webhook delivery is powered by Svix, and this connector is one of its advanced endpoint types.

Outbound webhooks are available on Team and Enterprise plans.

Prerequisites

A Postgres database reachable over the public internet
The destination table created before you enable the endpoint. The connector does not create or alter tables.
A dedicated database user that can connect to the database and insert into that table
Network rules that allow the connection, including any cloud provider IP allowlist

Do not reuse an application owner or migration account. The connector only needs to insert into one table.

Configuration

Field	Required	Description
Host	Yes	Hostname of the Postgres server.
Port	Yes	Port the Postgres server listens on.
Database	Yes	Database that contains the destination table.
Username	Yes	Database user the connector authenticates as.
Password	Yes	Password for that user.
Table name	Yes	Table that receives the event rows.
Transformation	Yes	JavaScript that maps each webhook batch to rows for that table.

Create the destination table

This schema keeps the event type available for filtering, extracts the two fields most reports need, and preserves the complete webhook body:

CREATE TABLE novu_events (
  id UUID PRIMARY KEY,
  event_type TEXT NOT NULL,
  subscriber_id TEXT,
  channel TEXT,
  payload JSONB NOT NULL,
  received_at TIMESTAMPTZ NOT NULL
);

CREATE INDEX novu_events_event_type_idx
  ON novu_events (event_type);

CREATE INDEX novu_events_received_at_idx
  ON novu_events (received_at DESC);

payload holds the full body as JSONB, so a new field in a Novu payload does not require a migration. received_at is set by the transformation rather than by the payload, which makes it a reliable sort key across every event type.

Grant least-privilege access

GRANT CONNECT ON DATABASE YOUR_DATABASE TO novu_webhook_writer;
GRANT USAGE ON SCHEMA public TO novu_webhook_writer;
GRANT INSERT ON TABLE public.novu_events TO novu_webhook_writer;

Replace the database, schema, user, and table names with your own. Add SELECT only if your verification process or database policy requires the same user to read rows back.

Transformation contract

The handler receives one delivery batch:

input.events, an array whose length is capped by the endpoint batch size
input.events[].eventType, the Novu event type, for example message.sent
input.events[].payload, the webhook body

The webhook body wraps the resource in an envelope. payload.object is the resource type as a string, such as "message", and the resource itself is under payload.data.object. For message events, fields such as subscriberId and channel are therefore at event.payload.data.object. Other event families use different resource shapes, so guard extracted fields with defaults. The return shape is defined by the template the Novu Dashboard ships with this connector. Open the template and read the JSDoc comment above its handler for the exact keys, because the return shape differs between connector families. Map the values below into that template rather than pasting a handler from another connector page:

Column	Value to map
`id`	`crypto.randomUUID()`
`event_type`	`event.eventType`
`subscriber_id`	`event.payload.data?.object?.subscriberId ?? null`
`channel`	`event.payload.data?.object?.channel ?? null`
`payload`	`JSON.stringify(event.payload)`
`received_at`	`new Date().toISOString()`

Send an example event before you customize anything, read the transformed output in the endpoint’s Logs, then change one column at a time and re-test.

Configure in the Dashboard

Prepare the database

Create the table, create the restricted user, and apply the grants above. Confirm the user can connect and insert from outside your network.

Add the endpoint

Open Webhooks in the Novu Dashboard, select Endpoints, click Add Endpoint, and choose .

Enter connection details

Enter the host, port, database, username, password, and table name. Add a description that identifies the database and environment.

Configure the transformation

Start from the transformation template shown in the Dashboard and map the columns using the table above.

Select event types

Subscribe to the event types your consumer needs. All subscribed types insert into the same table, so confirm the transformation produces valid rows for each one. For delivery reporting, start with message.sent, message.delivered, and message.failed.

Test the endpoint

Click Create, open the endpoint, go to the Testing tab, and use Send Example for each subscribed event type. Confirm success in the Logs tab.

Verify delivery

SELECT
  event_type,
  subscriber_id,
  channel,
  received_at
FROM novu_events
ORDER BY received_at DESC
LIMIT 20;

To read a field that you did not extract into a column, query the stored body:

SELECT payload #>> '{data,object,subscriberId}' AS subscriber_id
FROM novu_events
ORDER BY received_at DESC
LIMIT 20;

Troubleshooting

Symptom	What to check
Connection refused or timed out	Hostname, port, firewall rules, and any cloud provider IP allowlist.
Authentication failed	The username and password, and whether that user is allowed to connect to the selected database.
Permission denied on insert	The user needs `USAGE` on the schema and `INSERT` on the destination table.
Relation does not exist	The table must exist before the endpoint is enabled, and an unqualified name resolves through the user’s `search_path`.
Column or type error	Compare the transformed output in Logs with the table definition. A `TIMESTAMPTZ` column needs a valid timestamp, and a `NOT NULL` column cannot receive `null`.
Subscriber or channel values are empty	Message fields are under `payload.data.object`, not at the top level of `payload`. `payload.object` is the resource type string, such as `"message"`.
Rows appear for some event types but not others	The transformation assumes fields that only exist on certain event types. Guard each one with a default.
No rows after a successful delivery	Confirm the database, schema, and table you queried match the endpoint configuration.

Use the Logs tab to inspect transformed payloads and delivery attempts.

Guides

Insert webhook events into Postgres

Prerequisites

Configuration

Create the destination table

Grant least-privilege access

Transformation contract

Configure in the Dashboard

Prepare the database

Add the endpoint

Enter connection details

Configure the transformation

Select event types

Test the endpoint

Verify delivery

Troubleshooting

Official references

​Prerequisites

​Configuration

​Create the destination table

​Grant least-privilege access

​Transformation contract

​Configure in the Dashboard

​Prepare the database

​Add the endpoint

​Enter connection details

​Configure the transformation

​Select event types

​Test the endpoint

​Verify delivery

​Troubleshooting

​Related

​Official references

Prerequisites

Configuration

Create the destination table

Grant least-privilege access

Transformation contract

Configure in the Dashboard

Prepare the database

Add the endpoint

Enter connection details

Configure the transformation

Select event types

Test the endpoint

Verify delivery

Troubleshooting

Related

Official references