From 6f498bf279468a64dbfc7f9057be3aeb1c4a9839 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 9 Jun 2026 11:31:26 +0000 Subject: [PATCH 1/3] docs(platform): document new webhook vendor connectors fixes DOC-343 Add documentation for ClickHouse, Snowflake, Redshift, SQS, and SNS webhook connectors powered by Svix. Update the webhooks overview to reference connector endpoints alongside standard HTTP webhooks. Co-authored-by: Pawan Jain --- .../developer/webhooks/connectors.mdx | 157 ++++++++++++++++++ .../platform/developer/webhooks/index.mdx | 14 +- .../platform/developer/webhooks/meta.json | 2 +- 3 files changed, 166 insertions(+), 7 deletions(-) create mode 100644 content/docs/platform/developer/webhooks/connectors.mdx diff --git a/content/docs/platform/developer/webhooks/connectors.mdx b/content/docs/platform/developer/webhooks/connectors.mdx new file mode 100644 index 000000000..670adf72a --- /dev/null +++ b/content/docs/platform/developer/webhooks/connectors.mdx @@ -0,0 +1,157 @@ +--- +title: 'Webhook connectors' +pageTitle: 'Novu webhook connectors' +description: 'Send Novu webhook events directly to data warehouses, analytics databases, and AWS messaging services.' +--- + +In addition to standard HTTP webhook endpoints, Novu supports webhook connectors that deliver events directly to third-party services. These connectors are powered by [Svix](https://www.svix.com/) and let you route Novu events to data warehouses, analytics databases, and AWS messaging services without building a custom receiver. + +This webhook feature is only available on the Team and Enterprise plans. + +## How to add a connector endpoint + +1. Go to the **[Webhooks](https://dashboard.novu.co/webhooks)** page in the Novu dashboard. +2. Select the **Endpoints** tab. +3. Click **Add Endpoint**. +4. Search for or select the connector you want to use from the integrations list. + ![Webhook integrations list](/images/developer-tools/webhook-integrations.png) +5. Enter a **Description** to identify this endpoint. +6. Configure the connector-specific settings described in the sections below. +7. Select the [event types](/platform/developer/webhooks/event-types) you want this endpoint to subscribe to. +8. Click **Create**. + +After the endpoint is created, Novu delivers matching events to your configured destination. You can monitor delivery attempts, retry failed messages, and test the endpoint from the dashboard. + +## Available connectors + +Novu supports the following webhook connectors: + +| Connector | Description | +| --- | --- | +| [ClickHouse](#clickhouse) | Store events in a ClickHouse table. | +| [Snowflake](#snowflake) | Store events in a Snowflake table. | +| [Amazon Redshift](#amazon-redshift) | Store events in an Amazon Redshift table. | +| [Amazon SQS](#amazon-sqs) | Send events to an Amazon SQS queue. | +| [Amazon SNS](#amazon-sns) | Send events to an Amazon SNS topic. | + +## ClickHouse + +The ClickHouse connector stores Novu webhook events directly in a ClickHouse table. Use it when you want to analyze notification events in ClickHouse without building a custom ingestion pipeline. + +### Configuration + +| Field | Required | Description | +| --- | --- | --- | +| URL | Yes | The ClickHouse server URL (for example, `https://clickhouse.example.com:8443`). | +| Username | Yes | The username used to authenticate with ClickHouse. | +| Password | Yes | The password for the ClickHouse user. | +| Table name | Yes | The name of the table where events are stored. | +| Database | No | The ClickHouse database name. If omitted, the default database is used. | + +### Setup + +1. Create a ClickHouse table to receive webhook events. +2. Ensure the configured user has permission to insert rows into the target table. +3. In the Novu dashboard, select **ClickHouse** when adding a webhook endpoint and fill in the configuration fields. +4. Select the event types you want to store and create the endpoint. + +## Snowflake + +The Snowflake connector stores Novu webhook events directly in a Snowflake table. Use it when you want notification data available in your Snowflake data warehouse for reporting, analytics, or downstream pipelines. + +### Configuration + +| Field | Required | Description | +| --- | --- | --- | +| Account identifier | Yes | Your Snowflake account identifier. | +| User ID | Yes | The Snowflake user used to authenticate. | +| Private key | Yes | The private key for key-pair authentication. | +| Database name | No | The Snowflake database where events are stored. | +| Schema name | No | The schema containing the target table. | +| Table name | No | The table where events are stored. | + +### Setup + +1. Create a Snowflake table to receive webhook events. +2. Configure a Snowflake user with key-pair authentication and insert permissions on the target table. +3. In the Novu dashboard, select **Snowflake** when adding a webhook endpoint and fill in the configuration fields. +4. Select the event types you want to store and create the endpoint. + +## Amazon Redshift + +The Amazon Redshift connector stores Novu webhook events directly in a Redshift table. Use it when you want notification events available in your Redshift data warehouse for analytics and reporting. + +### Configuration + +| Field | Required | Description | +| --- | --- | --- | +| Region | Yes | The AWS region where your Redshift cluster or workgroup is located. | +| Access key ID | Yes | The AWS access key ID with permission to write to Redshift. | +| Secret access key | Yes | The AWS secret access key for the IAM user. | +| Cluster identifier | No | The Redshift cluster identifier. Required for provisioned clusters. | +| Workgroup name | No | The Redshift Serverless workgroup name. Required for serverless deployments. | +| Database user | No | The database user for provisioned clusters. | +| Database name | No | The Redshift database where events are stored. | +| Schema name | No | The schema containing the target table. | +| Table name | No | The table where events are stored. | + +For provisioned Redshift clusters, set **Cluster identifier** and **Database user**. For Redshift Serverless, set **Workgroup name** instead. + +### Setup + +1. Create a Redshift table to receive webhook events. +2. Create an IAM user with the permissions required to write data to Redshift. +3. In the Novu dashboard, select **Redshift** when adding a webhook endpoint and fill in the configuration fields. +4. Select the event types you want to store and create the endpoint. + +## Amazon SQS + +The Amazon SQS connector sends Novu webhook events to an Amazon SQS queue. Use it when you want to process notification events asynchronously through your existing AWS messaging infrastructure. + +### Configuration + +| Field | Required | Description | +| --- | --- | --- | +| Queue URL | Yes | The URL of the target SQS queue. | +| Region | Yes | The AWS region where the queue is located. | +| Access key ID | Yes | The AWS access key ID with permission to send messages to the queue. | +| Secret access key | Yes | The AWS secret access key for the IAM user. | +| Endpoint URL | No | A custom endpoint URL. Use this when connecting to LocalStack or other SQS-compatible services. | + +### Setup + +1. Create an SQS queue in your AWS account. +2. Create an IAM user with `sqs:SendMessage` permission on the target queue. +3. In the Novu dashboard, select **SQS** when adding a webhook endpoint and fill in the configuration fields. +4. Select the event types you want to deliver and create the endpoint. + +## Amazon SNS + +The Amazon SNS connector publishes Novu webhook events to an Amazon SNS topic. Use it when you want to fan out notification events to multiple subscribers through SNS. + +### Configuration + +| Field | Required | Description | +| --- | --- | --- | +| Topic ARN | Yes | The ARN of the target SNS topic. | +| Region | Yes | The AWS region where the topic is located. | +| Access key ID | Yes | The AWS access key ID with permission to publish to the topic. | +| Secret access key | Yes | The AWS secret access key for the IAM user. | +| Endpoint URL | No | A custom endpoint URL. Use this when connecting to LocalStack or other SNS-compatible services. | + +### Setup + +1. Create an SNS topic in your AWS account. +2. Create an IAM user with `sns:Publish` permission on the target topic. +3. In the Novu dashboard, select **SNS** when adding a webhook endpoint and fill in the configuration fields. +4. Select the event types you want to publish and create the endpoint. + +## Monitoring and troubleshooting + +Connector endpoints support the same delivery monitoring, retry, and recovery features as standard webhook endpoints. From the endpoint details page in the Novu dashboard, you can: + +- View delivery attempts and failure reasons in the **Logs** tab. +- Resend individual failed events. +- Recover or replay failed messages from a selected time window. + +If deliveries fail consistently, verify that your connector credentials are valid and that the destination service (database, queue, or topic) is accessible from Novu's webhook infrastructure. diff --git a/content/docs/platform/developer/webhooks/index.mdx b/content/docs/platform/developer/webhooks/index.mdx index 5bc7ccbf6..34abf6387 100644 --- a/content/docs/platform/developer/webhooks/index.mdx +++ b/content/docs/platform/developer/webhooks/index.mdx @@ -21,14 +21,16 @@ To start listening to messages, you must register your endpoint in the Novu dash 1. Go to the **[Webhooks](https://dashboard.novu.co/webhooks)** page in the Novu dashboard. 2. Select the **Endpoints** tab. 3. Click **Add Endpoint**. -4. Select a webhook integration from the list. +4. Select a webhook integration from the list. Choose **Webhook** to receive events over HTTP, or select a [connector](/platform/developer/webhooks/connectors) to deliver events directly to a data warehouse or AWS messaging service. ![Webhook integrations list](/images/developer-tools/webhook-integrations.png) -4. In the **Endpoint URL** field, enter the HTTPS URL where you want to receive the payload. You can use tools like [Webhook.site](https://webhook.site/) or [RequestBin](https://requestbin.com/) to generate a temporary URL for testing. -5. In the **Description** field, enter a description to identify this webhook. -6. Next, select the specific event types you want this endpoint to subscribe to. +5. Configure the endpoint: + - For **Webhook** endpoints, enter the HTTPS URL where you want to receive the payload. You can use tools like [Webhook.site](https://webhook.site/) or [RequestBin](https://requestbin.com/) to generate a temporary URL for testing. + - For connector endpoints (such as ClickHouse, Snowflake, Redshift, SQS, or SNS), enter the connector-specific configuration. See the [webhook connectors](/platform/developer/webhooks/connectors) guide for details. +6. In the **Description** field, enter a description to identify this webhook. +7. Next, select the specific event types you want this endpoint to subscribe to. ![Add webhook](/images/developer-tools/add-webhook.png) -7. (Optional) Configure [advanced settings](/platform/developer/webhooks#advanced-configuration) for rate limits, transformations, and custom headers. -8. Click **Create**. +8. (Optional) Configure [advanced settings](/platform/developer/webhooks#advanced-configuration) for rate limits, transformations, and custom headers. +9. Click **Create**. For frameworks that enable CSRF protection disable them and also verify the signature and timestamp when processing them. diff --git a/content/docs/platform/developer/webhooks/meta.json b/content/docs/platform/developer/webhooks/meta.json index 48f1a0db4..2145f183e 100644 --- a/content/docs/platform/developer/webhooks/meta.json +++ b/content/docs/platform/developer/webhooks/meta.json @@ -1,4 +1,4 @@ { "icon": "Webhook", - "pages": ["event-types"] + "pages": ["event-types", "connectors"] } From 7a53af5a08bed0bb65ba8110d3fabbd5bbf42794 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 9 Jun 2026 11:36:25 +0000 Subject: [PATCH 2/3] docs(platform): remove Svix mentions from webhook documentation Co-authored-by: Pawan Jain --- content/docs/platform/developer/webhooks/connectors.mdx | 2 +- content/docs/platform/developer/webhooks/index.mdx | 8 ++++---- content/docs/platform/developer/webhooks/webhooks.mdx | 8 +++----- 3 files changed, 8 insertions(+), 10 deletions(-) diff --git a/content/docs/platform/developer/webhooks/connectors.mdx b/content/docs/platform/developer/webhooks/connectors.mdx index 670adf72a..17522e5ef 100644 --- a/content/docs/platform/developer/webhooks/connectors.mdx +++ b/content/docs/platform/developer/webhooks/connectors.mdx @@ -4,7 +4,7 @@ pageTitle: 'Novu webhook connectors' description: 'Send Novu webhook events directly to data warehouses, analytics databases, and AWS messaging services.' --- -In addition to standard HTTP webhook endpoints, Novu supports webhook connectors that deliver events directly to third-party services. These connectors are powered by [Svix](https://www.svix.com/) and let you route Novu events to data warehouses, analytics databases, and AWS messaging services without building a custom receiver. +In addition to standard HTTP webhook endpoints, Novu supports webhook connectors that deliver events directly to third-party services. Use them to route Novu events to data warehouses, analytics databases, and AWS messaging services without building a custom receiver. This webhook feature is only available on the Team and Enterprise plans. diff --git a/content/docs/platform/developer/webhooks/index.mdx b/content/docs/platform/developer/webhooks/index.mdx index 34abf6387..2443e2132 100644 --- a/content/docs/platform/developer/webhooks/index.mdx +++ b/content/docs/platform/developer/webhooks/index.mdx @@ -40,7 +40,7 @@ When adding or editing an endpoint, you can utilize the advanced configuration o - **Rate limiting (Throttling)**: You can configure rate limits to effectively throttle the webhooks, ensuring Novu only sends a specific number of requests per second. - **Custom headers**: Custom headers can only be configured after the endpoint has been created. -- **Transformations**: Novu uses Svix transformations feature, it let's you modify a webhook's payload and redirect it to a different URL. Visit Svix documentation to learn more. +- **Transformations**: Modify a webhook's payload and redirect it to a different URL before delivery. ### Testing endpoints @@ -59,7 +59,7 @@ After sending an example event, you can view the message payload, all of the mes You must verify that the requests hitting your endpoint are actually from Novu and not a malicious actor. -Novu uses Svix to sign webhooks. Svix offers a set of libraries for verifying signatures. +Novu signs webhook requests so you can verify that payloads were sent by Novu. Official libraries are available for verifying signatures. ```tsx import { Webhook } from "svix"; @@ -79,7 +79,7 @@ const wh = new Webhook(secret); const verifiedPayload = wh.verify(payload, headers); ``` -Check out the Svix webhook verification documentation, for more instructions and examples of how to verify signatures. +See the library documentation for more instructions and examples of how to verify signatures in other languages. ## Recovery and resending failed messages @@ -182,7 +182,7 @@ For cases where your endpoint is processing complicated workflows, you can have To secure your webhook endpoint, you should: -1. Verify the webhook signature using the Svix library +1. Verify the webhook signature using the official verification library 2. Use HTTPS for your endpoint URL 3. Implement rate limiting to prevent abuse 4. Keep your webhook secret secure and rotate it periodically diff --git a/content/docs/platform/developer/webhooks/webhooks.mdx b/content/docs/platform/developer/webhooks/webhooks.mdx index c295c8171..804fe7712 100644 --- a/content/docs/platform/developer/webhooks/webhooks.mdx +++ b/content/docs/platform/developer/webhooks/webhooks.mdx @@ -88,9 +88,7 @@ After sending an example event, you can view the message payload, all of the mes Webhook signatures let you verify that webhook messages are actually sent by Novu and not a malicious actor. -For a more detailed explanation, check out this article on [why you should verify webhooks](https://docs.svix.com/receiving/verifying-payloads/why). - -Our webhook partner Svix offers a set of useful libraries that make verifying webhooks very simple. Here is an example using Javascript: +Verifying webhook signatures helps ensure payloads were sent by Novu and have not been tampered with. Here is an example using JavaScript: ```javascript import { Webhook } from "svix"; @@ -110,7 +108,7 @@ const wh = new Webhook(secret); const verifiedPayload = wh.verify(payload, headers); ``` -For more instructions and examples of how to verify signatures, check out the [webhook verification documentation](https://docs.svix.com/receiving/verifying-payloads/how). +See the library documentation for more instructions and examples of how to verify signatures in other languages. ## Retry schedule @@ -191,7 +189,7 @@ From there, you can click "Replay..." and choose to "Replay all failed messages To secure your webhook endpoint, you should: -1. Verify the webhook signature using the Svix library +1. Verify the webhook signature using the official verification library 2. Use HTTPS for your endpoint URL 3. Implement rate limiting to prevent abuse 4. Keep your webhook secret secure and rotate it periodically From fce47ba259a2f3450ed2082d722e3c1a2be762a8 Mon Sep 17 00:00:00 2001 From: Pawan Jain Date: Wed, 17 Jun 2026 12:38:56 +0530 Subject: [PATCH 3/3] docs(webhooks): enhance webhook connectors documentation Updated the webhook connectors guide to include details on Svix transformations, added specific instructions for data warehouse and message connectors, and clarified the setup process. Improved the structure and clarity of the content, including a new section on writing transformations and examples for better user guidance. --- .../developer/webhooks/connectors.mdx | 156 +++++++++++++++--- .../developer/webhooks/event-types.mdx | 1 + .../platform/developer/webhooks/index.mdx | 4 +- 3 files changed, 138 insertions(+), 23 deletions(-) diff --git a/content/docs/platform/developer/webhooks/connectors.mdx b/content/docs/platform/developer/webhooks/connectors.mdx index 17522e5ef..7f34c7327 100644 --- a/content/docs/platform/developer/webhooks/connectors.mdx +++ b/content/docs/platform/developer/webhooks/connectors.mdx @@ -2,11 +2,14 @@ title: 'Webhook connectors' pageTitle: 'Novu webhook connectors' description: 'Send Novu webhook events directly to data warehouses, analytics databases, and AWS messaging services.' +icon: 'Plug' --- In addition to standard HTTP webhook endpoints, Novu supports webhook connectors that deliver events directly to third-party services. Use them to route Novu events to data warehouses, analytics databases, and AWS messaging services without building a custom receiver. -This webhook feature is only available on the Team and Enterprise plans. +Novu webhook delivery is powered by [Svix](https://docs.svix.com/introduction). Connector endpoints use Svix [transformations](https://docs.svix.com/transformations) to shape each event before it is written to your destination. + +Outbound webhooks feature is only available in the Team and Enterprise plans. ## How to add a connector endpoint @@ -16,9 +19,12 @@ In addition to standard HTTP webhook endpoints, Novu supports webhook connectors 4. Search for or select the connector you want to use from the integrations list. ![Webhook integrations list](/images/developer-tools/webhook-integrations.png) 5. Enter a **Description** to identify this endpoint. -6. Configure the connector-specific settings described in the sections below. -7. Select the [event types](/platform/developer/webhooks/event-types) you want this endpoint to subscribe to. -8. Click **Create**. +6. Configure the connector-specific connection settings described in the sections below. +7. For **data warehouse connectors** (ClickHouse, Snowflake, Redshift): define the **table schema** and write a **transformation** that maps Novu webhook payloads to rows matching that schema. See [Data warehouse connectors](#data-warehouse-connectors). +8. For **message connectors** (Amazon SQS, Amazon SNS): review and customize the **transformation** that shapes the message body sent to the queue or topic. See [Message connectors](#message-connectors). +9. Select the [event types](/platform/developer/webhooks/event-types) you want this endpoint to subscribe to. +10. Click **Create**. +11. Open the endpoint, go to the **Testing** tab, and **Send Example** for each subscribed event type. Confirm delivery succeeds in **Logs**, then verify the row or message appears in your destination. After the endpoint is created, Novu delivers matching events to your configured destination. You can monitor delivery attempts, retry failed messages, and test the endpoint from the dashboard. @@ -26,13 +32,98 @@ After the endpoint is created, Novu delivers matching events to your configured Novu supports the following webhook connectors: -| Connector | Description | +| Connector | Type | Description | +| --- | --- | --- | +| [ClickHouse](#clickhouse) | Data warehouse | Store events in a ClickHouse table. | +| [Snowflake](#snowflake) | Data warehouse | Store events in a Snowflake table. | +| [Amazon Redshift](#amazon-redshift) | Data warehouse | Store events in an Amazon Redshift table. | +| [Amazon SQS](#amazon-sqs) | Message | Send events to an Amazon SQS queue. | +| [Amazon SNS](#amazon-sns) | Message | Send events to an Amazon SNS topic. | + +Additional warehouse connectors (such as BigQuery) may appear in the dashboard. They follow the same **table schema + transformation** pattern described below. + +## Transformations + +Every connector endpoint runs a JavaScript **transformation** before delivery. The transformation converts the raw Novu webhook into the format your destination expects. + +In the Novu dashboard, configure the transformation when creating or editing a connector endpoint. Each connector type ships with a default template—use it as your starting point. + +### How to write a transformation + +Svix expects a function named `handler`. For connector endpoints, the handler receives a `webhook` object with: + +| Property | Description | | --- | --- | -| [ClickHouse](#clickhouse) | Store events in a ClickHouse table. | -| [Snowflake](#snowflake) | Store events in a Snowflake table. | -| [Amazon Redshift](#amazon-redshift) | Store events in an Amazon Redshift table. | -| [Amazon SQS](#amazon-sqs) | Send events to an Amazon SQS queue. | -| [Amazon SNS](#amazon-sns) | Send events to an Amazon SNS topic. | +| `webhook.eventType` | The Novu event type (for example, `message.sent`). | +| `webhook.payload` | The webhook JSON body. Shape depends on the event type—see [event types](/platform/developer/webhooks/event-types). | +| `webhook.method` | HTTP method. Usually `"POST"`. | +| `webhook.url` | Destination URL. Generally leave unchanged for connectors. | +| `webhook.cancel` | Set to `true` to skip delivery for a given event. Defaults to `false`. | + +The handler must return the `webhook` object after modifying `webhook.payload` (and optionally other allowed properties). Test your code in the dashboard against a sample payload before going live. + +Handle every [event type](/platform/developer/webhooks/event-types) your endpoint subscribes to. Use `switch (webhook.eventType)` or equivalent logic so each event maps to a valid destination record. + +## Data warehouse connectors + +Data warehouse connectors (ClickHouse, Snowflake, Redshift, and similar) insert one row per delivered webhook. Credentials and table location alone are not enough—you must also configure: + +1. **Table schema** — Column names and types that match your destination table. +2. **Transformation** — JavaScript that maps each webhook `eventType` and `payload` into a row compatible with that schema. + +### Recommended setup flow + +1. **Create the destination table** in your warehouse with columns for the fields you want to store (for example, `event_type`, `message_id`, `subscriber_id`, `payload`, `created_at`). +2. **Grant insert permissions** to the user or role Novu connects with. +3. **Add the connector endpoint** in Novu and fill in connection settings (URL, credentials, database, table name, and so on). +4. **Define the table schema** in the connector configuration so it matches your destination table. +5. **Write the transformation** to map Novu payloads into that schema. Start from the dashboard template and adjust field names and types for your table. +6. **Subscribe** to the event types you want to store. +7. **Test** with **Send Example**, confirm success in **Logs**, then query the table to verify rows were inserted. + +### Example transformation + +This example maps a `message.sent` event into a flat row. Adjust field names to match your table schema and add cases for every event type you subscribe to. + +```js +function handler(webhook) { + switch (webhook.eventType) { + case "message.sent": + webhook.payload = { + event_type: webhook.eventType, + message_id: webhook.payload.id, + subscriber_id: webhook.payload.subscriberId, + channel: webhook.payload.channel, + created_at: webhook.payload.createdAt, + raw_payload: JSON.stringify(webhook.payload), + }; + break; + // Add a case for each subscribed event type + } + return webhook; +} +``` + +If deliveries succeed in Novu but no rows appear in your warehouse, the transformation output likely does not match your table schema. Compare the transformed payload in the **Logs** tab with your table definition. + +## Message connectors + +Message connectors (Amazon SQS and Amazon SNS) publish each webhook as a queue message or topic notification. Use the transformation to shape the JSON body your consumers receive. + +The default template typically forwards the webhook payload. Customize it if downstream workers expect a specific structure (for example, flattening nested fields or adding metadata). + +```js +function handler(webhook) { + webhook.payload = { + eventType: webhook.eventType, + data: webhook.payload, + receivedAt: new Date().toISOString(), + }; + return webhook; +} +``` + +After creating the endpoint, send a test event and confirm the message appears in your SQS queue or SNS topic subscription. ## ClickHouse @@ -47,13 +138,16 @@ The ClickHouse connector stores Novu webhook events directly in a ClickHouse tab | Password | Yes | The password for the ClickHouse user. | | Table name | Yes | The name of the table where events are stored. | | Database | No | The ClickHouse database name. If omitted, the default database is used. | +| Table schema | Yes | Column definitions that match your ClickHouse table. | +| Transformation | Yes | JavaScript that maps webhook payloads to rows matching the table schema. | ### Setup 1. Create a ClickHouse table to receive webhook events. 2. Ensure the configured user has permission to insert rows into the target table. -3. In the Novu dashboard, select **ClickHouse** when adding a webhook endpoint and fill in the configuration fields. -4. Select the event types you want to store and create the endpoint. +3. In the Novu dashboard, select **ClickHouse** when adding a webhook endpoint. +4. Fill in connection settings, **table schema**, and **transformation**. +5. Select event types, create the endpoint, and verify rows with **Send Example**. ## Snowflake @@ -69,13 +163,16 @@ The Snowflake connector stores Novu webhook events directly in a Snowflake table | Database name | No | The Snowflake database where events are stored. | | Schema name | No | The schema containing the target table. | | Table name | No | The table where events are stored. | +| Table schema | Yes | Column definitions that match your Snowflake table. | +| Transformation | Yes | JavaScript that maps webhook payloads to rows matching the table schema. | ### Setup 1. Create a Snowflake table to receive webhook events. 2. Configure a Snowflake user with key-pair authentication and insert permissions on the target table. -3. In the Novu dashboard, select **Snowflake** when adding a webhook endpoint and fill in the configuration fields. -4. Select the event types you want to store and create the endpoint. +3. In the Novu dashboard, select **Snowflake** when adding a webhook endpoint. +4. Fill in connection settings, **table schema**, and **transformation**. +5. Select event types, create the endpoint, and verify rows with **Send Example**. ## Amazon Redshift @@ -94,6 +191,8 @@ The Amazon Redshift connector stores Novu webhook events directly in a Redshift | Database name | No | The Redshift database where events are stored. | | Schema name | No | The schema containing the target table. | | Table name | No | The table where events are stored. | +| Table schema | Yes | Column definitions that match your Redshift table. | +| Transformation | Yes | JavaScript that maps webhook payloads to rows matching the table schema. | For provisioned Redshift clusters, set **Cluster identifier** and **Database user**. For Redshift Serverless, set **Workgroup name** instead. @@ -101,8 +200,9 @@ The Amazon Redshift connector stores Novu webhook events directly in a Redshift 1. Create a Redshift table to receive webhook events. 2. Create an IAM user with the permissions required to write data to Redshift. -3. In the Novu dashboard, select **Redshift** when adding a webhook endpoint and fill in the configuration fields. -4. Select the event types you want to store and create the endpoint. +3. In the Novu dashboard, select **Redshift** when adding a webhook endpoint. +4. Fill in connection settings, **table schema**, and **transformation**. +5. Select event types, create the endpoint, and verify rows with **Send Example**. ## Amazon SQS @@ -117,13 +217,15 @@ The Amazon SQS connector sends Novu webhook events to an Amazon SQS queue. Use i | Access key ID | Yes | The AWS access key ID with permission to send messages to the queue. | | Secret access key | Yes | The AWS secret access key for the IAM user. | | Endpoint URL | No | A custom endpoint URL. Use this when connecting to LocalStack or other SQS-compatible services. | +| Transformation | Yes | JavaScript that shapes the message body sent to the queue. | ### Setup 1. Create an SQS queue in your AWS account. 2. Create an IAM user with `sqs:SendMessage` permission on the target queue. -3. In the Novu dashboard, select **SQS** when adding a webhook endpoint and fill in the configuration fields. -4. Select the event types you want to deliver and create the endpoint. +3. In the Novu dashboard, select **SQS** when adding a webhook endpoint. +4. Fill in connection settings and review the **transformation**. +5. Select event types, create the endpoint, and verify messages with **Send Example**. ## Amazon SNS @@ -138,20 +240,32 @@ The Amazon SNS connector publishes Novu webhook events to an Amazon SNS topic. U | Access key ID | Yes | The AWS access key ID with permission to publish to the topic. | | Secret access key | Yes | The AWS secret access key for the IAM user. | | Endpoint URL | No | A custom endpoint URL. Use this when connecting to LocalStack or other SNS-compatible services. | +| Transformation | Yes | JavaScript that shapes the notification body published to the topic. | ### Setup 1. Create an SNS topic in your AWS account. 2. Create an IAM user with `sns:Publish` permission on the target topic. -3. In the Novu dashboard, select **SNS** when adding a webhook endpoint and fill in the configuration fields. -4. Select the event types you want to publish and create the endpoint. +3. In the Novu dashboard, select **SNS** when adding a webhook endpoint. +4. Fill in connection settings and review the **transformation**. +5. Select event types, create the endpoint, and verify messages with **Send Example**. ## Monitoring and troubleshooting Connector endpoints support the same delivery monitoring, retry, and recovery features as standard webhook endpoints. From the endpoint details page in the Novu dashboard, you can: - View delivery attempts and failure reasons in the **Logs** tab. +- Inspect the transformed payload sent to your destination. - Resend individual failed events. - Recover or replay failed messages from a selected time window. -If deliveries fail consistently, verify that your connector credentials are valid and that the destination service (database, queue, or topic) is accessible from Novu's webhook infrastructure. +If deliveries fail consistently, check the following: + +| Symptom | What to check | +| --- | --- | +| Authentication errors | Connector credentials, IAM permissions, or database user grants. | +| Schema or type errors | Table schema matches your destination table; transformation output uses the correct column names and types. | +| Missing rows or messages | Delivery shows success in **Logs** but destination is empty—transformation may not match the expected insert or message format. | +| Unhandled event types | Transformation includes a branch for every subscribed [event type](/platform/developer/webhooks/event-types). | + +If the destination service is unreachable from Novu's webhook infrastructure, deliveries will continue to retry according to the [retry schedule](/platform/developer/webhooks#recovery-and-resending-failed-messages) before the endpoint is disabled. diff --git a/content/docs/platform/developer/webhooks/event-types.mdx b/content/docs/platform/developer/webhooks/event-types.mdx index 56de1bf07..6377361d3 100644 --- a/content/docs/platform/developer/webhooks/event-types.mdx +++ b/content/docs/platform/developer/webhooks/event-types.mdx @@ -2,6 +2,7 @@ title: 'Event types' pageTitle: "Webhooks event types" description: 'Learn more about the types of events that Novu sends webhook events for.' +icon: 'Tags' --- Novu supports the following webhook event types: diff --git a/content/docs/platform/developer/webhooks/index.mdx b/content/docs/platform/developer/webhooks/index.mdx index 2443e2132..1667ade3c 100644 --- a/content/docs/platform/developer/webhooks/index.mdx +++ b/content/docs/platform/developer/webhooks/index.mdx @@ -6,7 +6,7 @@ description: "Configure webhook endpoints to receive real-time event notificatio Webhooks makes it possible for your external systems to receive real-time notifications when specific events occur within your Novu account. They are POST requests sent to a pre-determined endpoint that you configure. -This webhook feature is only have in the Team and Enterprise plans. +Outbound webhooks feature is only available in the Team and Enterprise plans. ## How it works @@ -25,7 +25,7 @@ To start listening to messages, you must register your endpoint in the Novu dash ![Webhook integrations list](/images/developer-tools/webhook-integrations.png) 5. Configure the endpoint: - For **Webhook** endpoints, enter the HTTPS URL where you want to receive the payload. You can use tools like [Webhook.site](https://webhook.site/) or [RequestBin](https://requestbin.com/) to generate a temporary URL for testing. - - For connector endpoints (such as ClickHouse, Snowflake, Redshift, SQS, or SNS), enter the connector-specific configuration. See the [webhook connectors](/platform/developer/webhooks/connectors) guide for details. + - For connector endpoints (such as ClickHouse, Snowflake, Redshift, SQS, or SNS), enter the connector-specific configuration, table schema (for warehouse connectors), and transformation code. See the [webhook connectors](/platform/developer/webhooks/connectors) guide for details. 6. In the **Description** field, enter a description to identify this webhook. 7. Next, select the specific event types you want this endpoint to subscribe to. ![Add webhook](/images/developer-tools/add-webhook.png)