SendGrid Email Activity Tracking Setup

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.
4. Set the key permissions to either:
   • Full Access, or
   • Custom Access with at least the following enabled:
     • Mail Send
     • Mail Settings
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.

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 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

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, enable at least the events you want Novu to process:

   SendGrid action	Novu activity status	Outbound webhook event (if enabled)
   Delivered	delivered	message.delivered
   Open	opened	message.seen
   Bounce	bounced	message.failed
   Dropped	dropped	message.failed
   Blocked	blocked	message.failed

   

10. Under Signature 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 webhook — a menu will appear.
4. Click Edit.
5. Enable Signed Webhook Verification if it hasn't been enabled. A Verification Key will be displayed.
6. Copy the verification key.
7. Return to your Novu SendGrid integration settings.
8. Paste the key you just copied from SendGrid into the Inbound Webhook Signing Key field.
9. Click Save.

Your SendGrid integration is now manually configured to send activity data to Novu.

Troubleshooting

Opens appear in SendGrid but not in Novu

Seeing an open in SendGrid's activity feed or in a third-party tool (for example, Datadog) does not guarantee SendGrid posted that event to Novu's inbound URL.

1. In SendGrid → Event Webhook → open the webhook that points to Novu → check delivery history.
2. Confirm open events are listed and return a 2xx response.
3. Confirm Open is enabled under Actions to be posted on that same webhook (not only on a separate webhook to another service).
4. Confirm the Post URL matches the Inbound Webhook URL from the SendGrid integration that sent the email.

message.sent works but message.delivered or message.seen does not

message.sent fires when Novu hands the email to SendGrid. message.delivered and message.seen only arrive after SendGrid posts back to Novu's inbound webhook. See Webhook event types for details.