Insert webhook events into ClickHouse

The ClickHouse connector inserts Novu webhook events into a ClickHouse table over the ClickHouse HTTP interface. Use it when you want notification events in ClickHouse for analytics without running your own ingestion service. Novu webhook delivery is powered by Svix. This connector maps to the Svix ClickHouse advanced endpoint.

Outbound webhooks are available on Team and Enterprise plans.

Prerequisites

A ClickHouse server reachable over its HTTP or HTTPS interface, for example port 8443 for HTTPS or 8123 for HTTP. The native protocol port (9000) is not used.
A ClickHouse user with a password and INSERT permission on the destination table.
The destination table created before you enable the endpoint. The connector does not create or alter tables.

Configuration

Field	Required	Description
URL	Yes	HTTP URL of the ClickHouse server, for example `https://clickhouse.example.com:8443`.
Username	Yes	ClickHouse user used to authenticate.
Password	Yes	Password for that user.
Table name	Yes	Table that receives the rows.
Database	No	Database that contains the table. Defaults to `default`.
Transformation	No	JavaScript that maps each webhook batch to rows. Required when your table columns do not match the top-level keys of the webhook body.

Grant insert permission

Give the connector user insert access on the destination table only. ClickHouse GRANT syntax:

GRANT INSERT ON analytics.novu_events TO novu_writer;

Default destination behavior

Without a transformation, Svix inserts each webhook payload directly using the ClickHouse JSONEachRow format. Top-level payload fields are matched to columns by name. ClickHouse is different from the other warehouse connectors in one important way: it does not add any columns of its own. There is no generated id column and no payload column unless you define them. You own the full schema. Novu webhook bodies are nested, and message fields such as subscriberId and channel sit under data.object rather than at the top level. Because of that, plan on writing a transformation for this connector unless your table columns exactly match the top-level keys of the webhook body.

Create the destination table

This table stores a few flattened fields plus the full webhook body:

CREATE TABLE novu_events (
  event_type String,
  subscriber_id String,
  channel String,
  payload String,
  received_at DateTime DEFAULT now()
)
ENGINE = MergeTree()
ORDER BY (event_type, subscriber_id);

received_at is not returned by the transformation below. Columns omitted from a JSONEachRow row take their declared default, so ClickHouse fills the insert time.

Transformation contract

The transformation receives one batch and returns the rows to insert: 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.

Output: an object with a rows array. Each row is an object whose keys match your ClickHouse column names. Each row is inserted separately using JSONEachRow.

Novu-oriented example that reads message fields from event.payload.data.object:

function handler(input) {
  const rows = input.events.map((event) => {
    const message = event.payload.data?.object ?? {};

    return {
      event_type: event.eventType,
      subscriber_id: String(message.subscriberId ?? ""),
      channel: String(message.channel ?? ""),
      payload: JSON.stringify(event.payload),
    };
  });

  return { rows };
}

Stringify nested values. A row value that is itself an object or array will not insert into a String column.

Configure in the Dashboard

Add the endpoint

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

Enter connection details

Enter the URL, username, password, table name, and database.

Configure the transformation

Paste the transformation above and adjust the keys so they match your column names exactly.

Select event types

Subscribe to the event types you want to store. If you subscribe to more than one, confirm the transformation produces valid rows for every one of them, since a single table receives all of them.

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

Query the table with clickhouse-client:

clickhouse-client --host clickhouse.example.com --secure \
  --user novu_writer --password "$CLICKHOUSE_PASSWORD" \
  --query "SELECT event_type, subscriber_id, channel, received_at FROM analytics.novu_events ORDER BY received_at DESC LIMIT 10"

Or over the same HTTP interface the connector uses:

curl -u "novu_writer:$CLICKHOUSE_PASSWORD" \
  --data-urlencode "query=SELECT count() FROM analytics.novu_events" \
  "https://clickhouse.example.com:8443/"

Troubleshooting

Symptom	What to check
Insert fails on an unknown field	The transformation returned a key that has no matching column. Remove the key or add the column.
Type errors on insert	A row value is an object or array being written to a scalar column. Wrap it in `JSON.stringify`.
Connection or timeout errors	The URL points at the native protocol port instead of the HTTP interface, or the server is not reachable from Novu. Use the HTTP or HTTPS port.
Authentication failures	Username or password is wrong, or the user lacks `INSERT` on the table.
Rows appear for some event types but not others	The transformation assumes fields that only exist on certain event types. Guard with defaults, as in the example above.
Table does not exist errors	The table must exist before the endpoint is enabled, and `database` defaults to `default` when left blank.

Guides

Insert webhook events into ClickHouse

Prerequisites

Configuration

Grant insert permission

Default destination behavior

Create the destination table

Transformation contract

Configure in the Dashboard

Add the endpoint

Enter connection details

Configure the transformation

Select event types

Test the endpoint

Verify delivery

Troubleshooting

Official references

​Prerequisites

​Configuration

​Grant insert permission

​Default destination behavior

​Create the destination table

​Transformation contract

​Configure in the Dashboard

​Add the endpoint

​Enter connection details

​Configure the transformation

​Select event types

​Test the endpoint

​Verify delivery

​Troubleshooting

​Related

​Official references

Prerequisites

Configuration

Grant insert permission

Default destination behavior

Create the destination table

Transformation contract

Configure in the Dashboard

Add the endpoint

Enter connection details

Configure the transformation

Select event types

Test the endpoint

Verify delivery

Troubleshooting

Related

Official references