Content for email activity tracking

content/docs/platform/developer/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["webhooks"]
+}

content/docs/platform/concepts/webhooks.mdx → content/docs/platform/developer/webhooks.mdx

@@ -1,6 +1,6 @@
 ---
-title: 'Outbound Webhooks'
-pageTitle: 'Outbound Webhooks'
+title: 'Webhooks'
+pageTitle: 'Webhooks'
 description: 'Receive notifications when events occur in your Novu account'
 icon: 'Webhook'
 ---

content/docs/platform/integrations/email/activity-tracking/index.mdx

@@ -0,0 +1,141 @@
+---
+pageTitle: 'Activity Tracking'
+title: 'Activity Tracking'
+description: 'Learn how to enable activity tracking to get real-time delivery and engagement events like delivered, opened, and clicked from your email providers.'
+---
+
+Activity tracking gives you visibility into what happens to notifications after they are sent to the subscriber. With it, Novu receive and process real-time events from third-party providers, so that you know when the notification is delivered, opened, clicked, or bounced.
+
+## How activity tracking works
+
+When your provider emits an event (for example, an email delivered or bounced), Novu:
+- Receives the event via inbound webhooks.
+- Create step-run trace, so the event is visible in the activity feed.
+- Forwards supported events to outbound webhooks if they are enabled in your project.
+- Enriches the workflow-run lifecycle with engagement and delivery data, which empowers analytics and workflow variables.
+
+With activity tracking enabled, you get a full picture of the workflow-run lifecycle, not just that a message was “sent,” but whether it reached the recipient, was opened, or engaged with. This closes the feedback loop and allows you to build more reliable notification experiences.
+
+## How to enable activity tracking
+
+First [create the integration](/platform/integrations/email/adding-email). After that, you can enable activity tracking by following these steps:
+1. Log in to the Novu dashboard
+2. Navigate to the **Integrations Store** page from the sidebar of your Novu dashboard.
+3. Click **Connect Provider** and select the email provider you want to configure.
+4. Scroll down to find the **Email Activity Tracking** section and click the toggle to enable it.
+  ![Enable the inbound webhook](/images/developer-tools/enable-inbound.png)
+  When enabled, Novu will auto-configure delivery webhooks using your existing API key.
+  ![Inbound webhook enabled](/images/developer-tools/inbound-enabled.png)
+
+## Manual configuration
+
+If auto-configuration fails or isn’t supported for your provider, you will need to set it up manually. You can do that by  following these provider specific guides:
+
+<Cards>
+  <Card title="Email" href="/platform/integrations/email">
+    Amazon SES
+  </Card>
+  <Card title="SMS" href="/platform/integrations/sms">
+    Mailgun
+  </Card>
+  <Card title="SendGrid" href="/platform/integrations/email/activity-tracking/manual-configuration/sendgrid">
+    SendGrid manual configuration
+  </Card>
+  <Card title="Chat" href="/platform/integrations/chat">
+    Resend
+  </Card>
+</Cards>
+
+## Event semantics in Novu
+
+Inbound webhook events are normalized into a consistent set of Novu event statuses. These statuses let you track the full lifecycle of a notification across providers in a unified way.
+
+| Novu status    | Meaning                                                                               |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `bounced`      | The message was rejected by the recipient’s server (hard or soft bounce).             |
+| `clicked`      | The recipient clicked a link inside the message.                                      |
+| `complaint`    | The recipient marked the message as spam or filed a complaint.                        |
+| `delayed`      | The provider delayed the message delivery (for example, due to throttling).                  |
+| `delivered`    | The provider confirmed that the message was delivered to the recipient’s server.      |
+| `dropped`      | The provider dropped the message before attempting delivery.                          |
+| `opened`       | The recipient opened the message (tracked via the provider’s open logic).             |
+| `rejected`     | The provider could not send the message (for example, invalid address, failed policy check). |
+| `sent`         | The provider has accepted the message for delivery.                                   |
+| `unsubscribed` | The recipient unsubscribed from further messages.                                     |
+
+## Supported providers and events
+
+Novu currently supports inbound webhooks for several email providers. Each provider sends events in its own format, which Novu normalizes into a consistent set of internal statuses. These normalized statuses are used in the activity feed, step-run traces, and outbound webhook forwarding.
+
+Events not listed in the tables below are ignored.
+
+### SendGrid
+
+| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) |
+| ---------------------------------- | ---------------------------------- |
+| `bounce`                           | `bounced`                          |
+| `click`                            | `clicked`                          |
+| `delivered`                        | `delivered`                        |
+| `dropped`                          | `dropped`                          |
+| `open`                             | `opened`                           |
+
+### Mailgun
+
+| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) |
+| ---------------------------------- | ---------------------------------- |
+| `clicked`                          | `clicked`                          |
+| `complained`                       | `complaint`                        |
+| `delivered`                        | `delivered`                        |
+| `opened`                           | `opened`                           |
+| `permanent_fail`, `failed`         | `rejected`                         |
+| `unsubscribed`                     | `unsubscribed`                     |
+
+### Resend
+
+| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) |
+| ---------------------------------- | ---------------------------------- |
+| `email.bounced`                    | `bounced`                          |
+| `email.clicked`                    | `clicked`                          |
+| `email.complained`                 | `complaint`                        |
+| `email.delivered`                  | `delivered`                        |
+| `email.delivery_delayed`           | `delayed`                          |
+| `email.failed`                     | `rejected`                         |
+| `email.opened`                     | `opened`                           |
+| `email.sent`                       | `sent`                             |
+
+### Amazon SES
+
+| Provider event (`<native_status>`) | Novu event (`<novu_event_status>`) |
+| ---------------------------------- | ---------------------------------- |
+| `Bounce`                           | `bounced`                          |
+| `Complaint`                        | `complaint`                        |
+| `Click`                            | `clicked`                          |
+| `Delivery`                         | `delivered`                        |
+| `DeliveryDelay`                    | `delayed`                          |
+| `Open`                             | `opened`                           |
+| `Reject`                           | `rejected`                         |
+| `Send`                             | `sent`                             |
+
+## Viewing event data
+
+Once your inbound webhooks are configured, Novu will start processing events from your provider. You can see this new data in two key places within the platform.
+
+### Activity feed
+
+The Activity Feed provides the most direct view of the notification lifecycle. After a notification is sent, you will see new status updates such as Delivered, Opened, and Clicked appear in the timeline as they are received from your provider. This gives you a complete, real-time picture of subscriber engagement for each notification.
+
+### Outbound webhooks integration
+
+Inbound webhooks don’t just update Novu internally, they can also trigger outbound webhooks, allowing you to send normalized events to your own systems in real time. This makes it possible to extend Novu’s notification lifecycle into your existing infrastructure.
+
+How it works:
+
+1. A provider emits an event (for example, delivered).
+2. Novu receives and normalizes the event (for example, → delivered).
+3. Novu updates its internal message entity and step-run trace.
+4. If outbound webhooks are enabled, Novu forwards the normalized event to your configured outbound webhook endpoint.
+
+This is useful in a number of use cases including:
+- Internal logging: Forward all events into your organization’s centralized logging pipeline.
+- Custom analytics: Combine Novu’s lifecycle data with your own metrics to measure engagement and delivery performance.
+- Workflow triggers: Kick off custom business logic when specific events occur (for example, flagging accounts with high bounce rates).

content/docs/platform/integrations/email/activity-tracking/manual-configuration/mailgun.mdx

@@ -0,0 +1,48 @@
+---
+pageTitle: 'Mailgun manual configuration'
+title: 'Mailgun'
+description: 'A step-by-step guide to manually add specific event webhooks in Mailgun for Novu activity tracking.'
+---
+
+By default, Mailgun API keys have the required permissions for Novu to auto-configure webhooks when email activity tracking is enabled in the Novu dashboard. In most cases, you won’t need to do any manual setup. However, you might want to track specific Mailgun events the Novu supports.
+
+This guide explains how to manually add new webhooks for specific events directly from your Mailgun dashboard.
+
+## Step 1: Get your webhook URL from Novu
+
+First, you need the unique webhook URL from your Novu dashboard that will receive events from Mailgun.
+
+1. Log in to the Novu dashboard.
+2. Navigate to the **Integration Store** page in Novu and then select your **Mailgun** integration.
+3. Enable the **Email Activity Tracking** toggle.
+    This generates an Inbound Webhook URL unique to your integration. 
+
+4. Copy the URL, you’ll use it in the Mailgun dashboard if you want to add specific events manually.
+  ![Mailgun Inbound Webhook URL](/images/channels-and-providers/email/activity-tracking/mailgun.png)
+
+## Step 2: Add an event webhook in Mailgun
+
+Next, log in to your Mailgun account to create a new webhook for the specific event you want to track.
+
+1. Log in to your Mailgun account.
+2. Navigate to **Send** section in the left sidebar, and then select **Webhooks**.
+2. Click **Add webhook**.
+  ![Add Mailgun webhook](/images/channels-and-providers/email/activity-tracking/add-mailgun-webhook.png)
+3. A menu will appear. Configure the webhook with the following settings:
+    - **Event type:** Select the event you want to track from the dropdown menu.
+    - **URL:** Paste the **Inbound Webhook URL** you copied from Novu.
+4. Click **Create Webhook**.
+  ![Create Mailgun Webhook](/images/channels-and-providers/email/activity-tracking/create-mailgun-webhook.png)
+
+## Step 3: Add additional events (Optional)
+
+Your new webhook for the selected event is now active. To track other events, you must repeat the process in **Step 2** for each one. We recommend adding webhooks for all events that Novu supports:
+
+- Delivered messages
+- Opens
+- Clicks
+- Unsubscribes
+- Spam complaints
+- Permanent failures
+
+Once configured, Mailgun will begin sending real-time data for these events to Novu, which you can monitor in your **Activity Feed**.

content/docs/platform/integrations/email/activity-tracking/manual-configuration/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["ses", "mailgun", "resend", "sendgrid"]
+}

content/docs/platform/integrations/email/activity-tracking/manual-configuration/resend.mdx

@@ -0,0 +1,42 @@
+---
+pageTitle: 'Resend manual configuration'
+title: 'Resend'
+description: 'A step-by-step guide to manually configure Resend event webhooks for Novu activity tracking.'
+---
+
+Resend does not currently support auto-configuration of webhooks through their API. To track events in Novu, you’ll need to set up the webhook manually in your Resend dashboard.
+
+## Step 1: Get your webhook URL from Novu
+
+First, you need the unique webhook URL from your Novu dashboard that will receive events from Resend.
+
+1. Navigate to the **Integration Store** page in Novu and select your **Resend** integration.
+2. Enable the **Email Activity Tracking** toggle.
+3. A unique Inbound Webhook URL will be displayed. Click the **copy** icon to copy it.
+  ![Copy Webhook URL from Novu](/images/channels-and-providers/email/activity-tracking/inbound-webhook-resend.png)
+
+## Step 2: Create the webhook in Resend
+
+Next, log in to your Resend dashboard to create the webhook.
+
+1. From the sidebar menu of your Resend dashboard, click on **Webhooks**.
+2. On the webhooks page, click **Add webhook**.
+  ![Add webhook](/images/channels-and-providers/email/activity-tracking/resend-webhook.png)
+3. In the menu that appears, configure the following:
+    - **Endpoint URL:** Paste the **Inbound Webhook URL** you copied from Novu.
+    - **Events to send:** Select **Email** to subscribe to all email events.
+    ![Add webhook](/images/channels-and-providers/email/activity-tracking/add-webhook-resend.png)
+4.  Click **Add** to create the webhook.
+
+Your Resend account will now forward email events to Novu, where they will appear in the Activity Feed and the execution details in the event logs.
+
+## Step 3: Add the signing secret (Recommended)
+
+For a more secure and authenticated connection, you should add the webhook's signing secret back into Novu. This step is optional but highly recommended.
+
+1. After creating the webhook in Resend, you will get **Signing Secret**. Copy this secret.
+  ![Signing secret](/images/channels-and-providers/email/activity-tracking/signing-secret-resend.png)
+2. Return to your Resend integration settings in Novu.
+3. Under the **Email Activity Tracking** section, paste the secret into the **Inbound Webhook Signing Key** field.
+  ![Inbound Signing Key](/images/channels-and-providers/email/activity-tracking/inbound-signing-key-resend.png)
+4.  Click **Save Changes**.

content/docs/platform/integrations/email/activity-tracking/manual-configuration/sendgrid.mdx

@@ -0,0 +1,77 @@
+---
+pageTitle: 'SendGrid Manual Configuration'
+title: 'SendGrid'
+description: 'A step-by-step guide to manually configure SendGrid event webhooks for Novu activity tracking.'
+---
+
+If the API key used in your Novu SendGrid integration does not have the required permissions, the automatic setup will fail with an `access forbidden` error. This indicates that Novu lacks the permissions needed to configure the webhook on your behalf.
+
+This guide will walk you through resolving this issue.
+
+## Step 1: Update SendGrid API key permissions
+
+First, you need to update your API key in your SendGrid account to grant the necessary permissions.
+
+1. Log in to your SendGrid account.
+2. Under **Settings**, click **API Keys**.
+3. Choose whether to edit an existing key or create a new one:
+   - To create a new API key, click **Create API Key**.
+   - To update an existing key, click the settings icon next to it and select **Edit API Key**.
+   ![Edit existing key or creating a new one](/images/channels-and-providers/email/activity-tracking/sendgrid-api.png)
+4. Set the key permissions to either:
+   - **Full Access**, or
+   - Custom Access with at least the following enabled:  
+     - **Mail Send**
+     - **Mail Settings**
+     ![Custom access](/images/channels-and-providers/email/activity-tracking/custom-access.png)
+5. If you created a new key, return to the Novu dashboard and update your SendGrid integration settings with the new API key.
+
+## Step 2: Enable activity tracking in Novu
+Once your API key has the correct permissions, return to your Novu dashboard to complete the setup.
+
+1.  Navigate to the **Integrations** page and select your **SendGrid** integration.
+2.  Click the **Email Activity Tracking** toggle to enable it.
+
+With the updated permissions, Novu should now successfully auto-configure the webhook for you. You should see a green checkmark indicating that the webhook is active. If you see this, your setup is complete.
+
+![Enable activity tracking in Novu](/images/channels-and-providers/email/activity-tracking/enable-activity-tracking.gif)
+
+## Step 3: Manual configuration (only if auto-configuration fails)
+
+If the automatic configuration fails for any reason, or if you prefer to set it up manually, follow these steps.
+
+### Part 1: Configure the webhook in SendGrid
+
+1.  In your Novu SendGrid integration settings, enable the **Email Activity Tracking** toggle to reveal the **Inbound Webhook URL**
+2. Copy the this Inbound Webhook URL.
+3. Log in to the SendGrid dashboard.
+4. Go to the Settings page, and click **Mail Settings**.
+5. Click on **Event Webhook**.
+6. Click **Create new webhook**
+   ![Create new SendGrid webhook](/images/channels-and-providers/email/activity-tracking/sendgrid-webhook.png)
+7. Give the webhook a friendly name.
+8. Paste the Inbound Webhook URL copied from Novu into the **Post URL** field.
+9.  Under **Actions to be posted**, select the events Novu supports that you want to track
+   ![Add new event webhook](/images/channels-and-providers/email/activity-tracking/add-new-event-webhook.png)
+10. Under Singnature Verification, enable **Enable Signed Event Webhook**
+11. Click **Save**
+
+
+### Part 2: Add the signing key to Novu (Recommended)
+
+For enhanced security, you should add a signing key to verify that webhooks are coming from SendGrid.
+
+1. Log in to the SendGrid dashboard.
+2. Go to the Settings page, and click **Mail Settings**.
+3. Click the settings icon next to the webhhok a menu will appear.
+4. Click **Edit**.
+   ![Add new event webhook](/images/channels-and-providers/email/activity-tracking/edit-sendgrid-webhook.png)
+5. Enable **Signed Webhook Verification** if is hasn't been enabled. A **Verification Key** will be displayed. 
+6. Copy the verification key.
+   ![Add new event webhook](/images/channels-and-providers/email/activity-tracking/sendgrid-verification-key.png)
+3. Return to your Novu SendGrid integration settings.
+4. Paste the key you just copied from SendGrid into the **Inbound Webhook Signing Key** field.
+   ![Add new event webhook](/images/channels-and-providers/email/activity-tracking/inbound-signing-key-sendgrid.png)
+5. Click **Save**.
+
+Your SendGrid integration is now manually configured to send activity data to Novu.