diff --git a/content/docs/platform/developer/webhooks/event-types.mdx b/content/docs/platform/developer/webhooks/event-types.mdx index 6377361d3..07943e3b1 100644 --- a/content/docs/platform/developer/webhooks/event-types.mdx +++ b/content/docs/platform/developer/webhooks/event-types.mdx @@ -15,12 +15,34 @@ Each event includes detailed information about the affected resource and the cha ## Message events +### Where message events come from + +Not every `message.*` event is triggered the same way. Some fire when Novu sends a notification; others arrive later from your delivery provider or from subscriber actions in the Inbox. + +| Event | Typical source | Requires [Email Activity Tracking](/platform/integrations/email/activity-tracking)? | +| ----- | -------------- | ----------------------------------------------------------------------------------- | +| `message.sent` | Novu worker, right after the provider accepts the send | No | +| `message.failed` | Novu worker (send error) or provider bounce/drop via activity tracking | Partial — provider failures need activity tracking | +| `message.delivered` | Provider inbound webhook (for example, SendGrid `delivered`) | Yes, for email | +| `message.seen` | Provider inbound webhook (for example, SendGrid `open`) or Inbox | Yes, for email opens from the provider | + + +**`message.sent` vs `message.delivered` (email)** + +- **`message.sent`** means Novu successfully handed the email to SendGrid (or another provider). It fires immediately. +- **`message.delivered`** means the provider later confirmed the recipient's mail server received the email. It only arrives if [Email Activity Tracking](/platform/integrations/email/activity-tracking) is enabled on the integration that sent the message. + +Seeing `message.sent` in your outbound webhook logs does not mean delivery or open tracking is configured. + + +### Event reference + - `message.archived`: This webhook is triggered when a subscriber archives a message. The payload contains the details of the event. -- `message.delivered`: This webhook is triggered when a message delivery provider acknowledged the message delivery to the end receiving client. The payload contains the details of the event. -- `message.failed`: This webhook is triggered when Novu tries to send the message to the delivery provider and it got failed. The payload contains the details of the event. -- `message.read`: This webhook is triggered when a message has been read by the subscriber. The payload contains the details of the event. -- `message.seen`: This webhook is triggered when a subscriber opens a message. The payload contains the details of the event. -- `message.sent`: This webhook is triggered when Novu sends the message to the delivery provider. The payload contains the details of the event. +- `message.delivered`: This webhook is triggered when a delivery provider confirms the message was delivered to the recipient's mail server (for email, via [activity tracking](/platform/integrations/email/activity-tracking)). The payload contains the details of the event. +- `message.failed`: This webhook is triggered when Novu fails to send the message to the provider, or when the provider reports a bounce, drop, or block (via activity tracking). The payload contains the details of the event. +- `message.read`: This webhook is triggered when a message has been read by the subscriber (for example, via the Inbox). The payload contains the details of the event. +- `message.seen`: This webhook is triggered when a message is opened. For email, provider open events (for example, SendGrid `open`) are forwarded as `message.seen` — not `message.opened`. The payload contains the details of the event. +- `message.sent`: This webhook is triggered when Novu hands the message off to the delivery provider. The payload contains the details of the event. - `message.snoozed`: This webhook is triggered when a message is snoozed by the subscriber. The payload contains the details of the event. - `message.unarchived`: This webhook is triggered when an archived message is unarchived. The payload contains the details of the event. - `message.unread`: This webhook is triggered when a message is unread or marked as unread by the subscriber. The payload contains the details of the event. diff --git a/content/docs/platform/developer/webhooks/index.mdx b/content/docs/platform/developer/webhooks/index.mdx index 1667ade3c..8a4859578 100644 --- a/content/docs/platform/developer/webhooks/index.mdx +++ b/content/docs/platform/developer/webhooks/index.mdx @@ -190,3 +190,22 @@ To secure your webhook endpoint, you should: ### How can I test webhooks locally? To test webhooks locally, you can use a service like ngrok or localtunnel to expose your local server to the internet. Alternatively, you can use webhook testing services like Webhook.site or RequestBin to inspect webhook payloads. + +### Why do I see `message.sent` but not `message.delivered` or `message.seen` for email? + +These events come from different stages of the email lifecycle: + +- **`message.sent`** — Novu successfully sent the email to the provider (for example, SendGrid). This does not require [Email Activity Tracking](/platform/integrations/email/activity-tracking). +- **`message.delivered`** — The provider confirmed delivery to the recipient's mail server. Requires activity tracking on the sending integration. +- **`message.seen`** — The recipient opened the email. SendGrid `open` events are forwarded as `message.seen` (not `message.opened`). Requires activity tracking on the sending integration. + +You need both [Email Activity Tracking](/platform/integrations/email/activity-tracking) on your provider integration **and** an outbound webhook endpoint subscribed to `message.delivered` and `message.seen`. + +### I see delivery or open events in SendGrid but not in Novu outbound webhooks + +1. Confirm **Email Activity Tracking** is enabled on the SendGrid integration that sends your emails. +2. Confirm your outbound endpoint is subscribed to **`message.seen`** and **`message.delivered`** (not `message.opened`). +3. In SendGrid → **Event Webhook** → check **delivery history** for POSTs to your Novu inbound URL. The SendGrid activity UI and third-party integrations can show events that were never posted to Novu. +4. If you have multiple SendGrid integrations, verify the Event Webhook **Post URL** matches the [Inbound Webhook URL](/platform/integrations/email/activity-tracking/manual-configuration/sendgrid) for the integration that sends the emails. + +See the [SendGrid activity tracking troubleshooting](/platform/integrations/email/activity-tracking/manual-configuration/sendgrid#troubleshooting) section for more detail. diff --git a/content/docs/platform/developer/webhooks/webhooks.mdx b/content/docs/platform/developer/webhooks/webhooks.mdx index 804fe7712..b05cd7bae 100644 --- a/content/docs/platform/developer/webhooks/webhooks.mdx +++ b/content/docs/platform/developer/webhooks/webhooks.mdx @@ -4,204 +4,9 @@ pageTitle: "Novu Webhooks Guide" description: "Learn how Novu webhooks work, including event types, payload schemas, signature verification, and endpoint configuration." --- -## The Intro + +This page is a legacy draft. Use the current documentation instead: -Webhooks are how services notify each other of events. - -At their core they are just a POST request to a pre-determined endpoint. -The endpoint can be whatever you want, and you can just add them from the UI. -You normally use one endpoint per service, and that endpoint listens to all of the event types. - -For example, if you receive webhooks from Novu, you can structure your URL like: `https://www.example.com/novu/webhook/`. - -The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s). - -It's also important to disable CSRF protection for this endpoint if the framework you use enables them by default. - -Another important aspect of handling webhooks is to verify the signature and timestamp when processing them. - -You can learn more about it in the signature verification section. - -## Events and event types - -The core value of webhooks is to notify users when events happen, so it's extremely important to understand what events are available and their payload schemas. - -Novu webhooks allow you to receive notifications when specific events occur in your Novu account. These events include workflow updates, subscriber changes, and message delivery status updates. - -### Supported event types - -Novu supports the following webhook event types: - -- **Workflow Events**: Events about workflow creation, updates, and deletions, -- **Message Events**: Events about message delivery status changes -- **Preference Events**: Events about subscriber preference changes - -Each event includes detailed information about the affected resource and the changes that occurred. - -#### Workflow Events - -- **workflow.created**: Triggered when a workflow is created -- **workflow.updated**: Triggered when a workflow is updated -- **workflow.deleted**: Triggered when a workflow is deleted -- **workflow.published**: Triggered when a workflow is synced from dev to prod environment - -#### Message Events - -- **messages.archived**: Triggered when a message is archived. -- **messages.unarchived**: Triggered when a message is unarchived. -- **messages.read**: Triggered when a message is read. -- **messages.unread**: Triggered when a message is unread. -- **messages.seen**: Triggered when a message is seen. -- **messages.snoozed**: Triggered when a message is snoozed. -- **messages.unsnoozed**: Triggered when a message is unsnoozed. -- **messages.sent**: Triggered when Novu sends the message to the delivery provider. -- **messages.delivered**: Triggered when a message delivery provider acknowledged the message delivery to the end receiving client. -- **messages.failed**: Triggered when Novu tried to send the message to the delivery provider and it got failed. - -#### Preference Events - -- **preference.updated**: Triggered when subscriber preference is updated. - -## How to add an endpoint - -To start listening to messages, you will need to configure your endpoints. - -1. Go to the [Webhooks](https://dashboard.novu.co/webhooks) page in the Novu dashboard. -2. Click **Add Endpoint**. -3. Enter the URL of your endpoint. -4. Add description for this webhook endpoint. -5. Select the event types you want to listen to. -6. Optional: add advanced configuration for your endpoint. -7. Click **Create**. - -If your endpoint isn't quite ready to start receiving events, you can use a service like [Webhook.site](https://webhook.site/) or [RequestBin](https://requestbin.com/) to have a unique URL generated for you. - -## How to test endpoints - -Once you've added an endpoint, you'll want to make sure it's working. - -The "Testing" tab lets you send test events to your endpoint. - -After sending an example event, you can view the message payload, all of the message attempts, and whether it succeeded or failed. - -## Verifying signatures - -Webhook signatures let you verify that webhook messages are actually sent by Novu and not a malicious actor. - -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"; - -const secret = "YOUR_WEBHOOK_SECRET_KEY"; - -// These were all sent from the server -const headers = { - "webhook-id": "msg_p5jXN8AQM9LWM0D4loKWxJek", - "webhook-timestamp": "1614265330", - "webhook-signature": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=", -}; -const payload = '{"test": 2432232314}'; - -const wh = new Webhook(secret); -// Throws on error, returns the verified content on success -const verifiedPayload = wh.verify(payload, headers); -``` - -See the library documentation for more instructions and examples of how to verify signatures in other languages. - -## Retry schedule - -### Retries - -We attempt to deliver each webhook message based on a retry schedule with exponential backoff. - -#### The schedule - -Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt: - -- Immediately -- 5 seconds -- 5 minutes -- 30 minutes -- 2 hours -- 5 hours -- 10 hours -- 10 hours (in addition to the previous) - -If an endpoint is removed or disabled, delivery attempts to the endpoint will be disabled as well. - -For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt. - -### Manual retries - -You can also use the application portal to manually retry each message at any time, or automatically retry ("Recover") all failed messages starting from a given date. - -## Troubleshooting & Failure Recovery - -### Common reasons why your webhook endpoint is failing - -There are some common reasons why your webhook endpoint is failing: - -- **Not using the raw payload body** - -This is the most common issue. When generating the signed content, we use the raw string body of the message payload. - -If you convert JSON payloads into strings using methods like stringify, different implementations may produce different string representations of the JSON object, which can lead to discrepancies when verifying the signature. It's crucial to verify the payload exactly as it was sent, byte-for-byte or string-for-string, to ensure accurate verification. - -- **Missing the secret key** - -From time to time we see people simply using the wrong secret key. Remember that keys are unique to endpoints. - -- **Sending the wrong response codes** - -When we receive a response with a 2xx status code, we interpret that as a successful delivery even if you indicate a failure in the response payload. Make sure to use the right response status codes so we know when messages are supposed to succeed vs fail. - -- **Responses timing out** - -We will consider any message that fails to send a response within 15 seconds a failed message. If your endpoint is also processing complicated workflows, it may timeout and result in failed messages. - -We suggest having your endpoint simply receive the message and add it to a queue to be processed asynchronously so you can respond promptly and avoid getting timed out. - -### Re-enable a disabled endpoint - -If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. To re-enable a disabled endpoint, go to the webhook dashboard, find the endpoint from the list and select "Enable Endpoint". - -### Recovering/Resending failed messages - -If your service has downtime or if your endpoint was misconfigured, you probably want to recover any messages that failed during the downtime. - -If you want to replay a single event, you can find the message from the UI and click the options menu next to any of the attempts. - -From there, click "resend" to have the same message send to your endpoint again. - -If you need to recover from a service outage and want to replay all the events since a given time, you can do so from the Endpoint page. On an endpoint's details page, click "Options > Recover Failed Messages". - -From there, you can choose a time window to recover from. - -For a more granular recovery - for example, if you know the exact timestamp that you want to recover from - you can click the options menu on any message from the endpoint page. - -From there, you can click "Replay..." and choose to "Replay all failed messages since this time." - -## FAQs - -### How do I secure my webhook endpoint? - -To secure your webhook endpoint, you should: - -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 - -### What happens if my endpoint is unavailable? - -If your endpoint is unavailable, Novu will retry sending the webhook according to the retry schedule. If all attempts fail for 5 days, the endpoint will be disabled and you'll need to manually re-enable it. - -### Can I filter webhooks by event type? - -Yes, when configuring your webhook endpoint, you can select specific event types to receive. This allows you to filter out events that aren't relevant to your use case. - -### How can I test webhooks locally? - -To test webhooks locally, you can use a service like ngrok or localtunnel to expose your local server to the internet. Alternatively, you can use webhook testing services like Webhook.site or RequestBin to inspect webhook payloads. +- [Webhooks overview](/platform/developer/webhooks) — setup, signatures, retries, and troubleshooting +- [Event types](/platform/developer/webhooks/event-types) — full list of `message.*`, `workflow.*`, and `preference.*` events + diff --git a/content/docs/platform/integrations/email/activity-tracking/index.mdx b/content/docs/platform/integrations/email/activity-tracking/index.mdx index 5937d9fc1..7c3d08972 100644 --- a/content/docs/platform/integrations/email/activity-tracking/index.mdx +++ b/content/docs/platform/integrations/email/activity-tracking/index.mdx @@ -27,6 +27,15 @@ First [create the integration](/platform/integrations/email/adding-email). After When enabled, Novu will auto-configure delivery webhooks using your existing API key. ![Inbound webhook enabled](/images/developer-tools/inbound-enabled.png) + +**Activity tracking and outbound webhooks are two separate steps** + +1. **Email Activity Tracking** (this guide) — lets Novu receive delivery and engagement events from your provider via an inbound webhook. +2. **[Outbound Webhooks](/platform/developer/webhooks)** — forwards selected events to your own endpoint. Subscribe to `message.delivered` and `message.seen` to receive provider delivery and open events. + +Enabling only outbound webhooks is not enough. You must also enable activity tracking on the provider integration that sends your emails. + + ## 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: @@ -133,9 +142,23 @@ Inbound webhooks don’t just update Novu internally, they can also trigger outb How it works: 1. A provider emits an event (for example, delivered). -2. Novu receives and normalizes the 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. +4. If [outbound webhooks](/platform/developer/webhooks) are enabled, Novu forwards the event to your configured endpoint using the outbound event names below. + +#### Provider events → outbound webhook events + +| Provider event (example) | Novu activity status | Outbound webhook event | +| ---------------------- | -------------------- | ---------------------- | +| `delivered` | `delivered` | `message.delivered` | +| `open` | `opened` | `message.seen` | +| `bounce`, `dropped`, `blocked` | `bounced`, `dropped`, `blocked` | `message.failed` | + + +Email opens appear as **`message.seen`** in outbound webhooks, not `message.opened`. Subscribe to `message.seen` on your outbound webhook endpoint. + +Click events appear in the Novu activity feed but are **not** currently forwarded to outbound webhooks for email. + This is useful in a number of use cases including: - Internal logging: Forward all events into your organization’s centralized logging pipeline. diff --git a/content/docs/platform/integrations/email/activity-tracking/manual-configuration/sendgrid.mdx b/content/docs/platform/integrations/email/activity-tracking/manual-configuration/sendgrid.mdx index 48102a9d7..22124ba0e 100644 --- a/content/docs/platform/integrations/email/activity-tracking/manual-configuration/sendgrid.mdx +++ b/content/docs/platform/integrations/email/activity-tracking/manual-configuration/sendgrid.mdx @@ -27,23 +27,32 @@ First, you need to update your API key in your SendGrid account to grant the nec 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. +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) + +**Multiple SendGrid integrations** + +Each Novu SendGrid integration has its own **Inbound Webhook URL** (it includes a unique `integrationId`). Your SendGrid Event Webhook **Post URL** must match the integration that actually sends your emails. + +If you use more than one SendGrid integration, pick one primary integration for activity tracking and point SendGrid to that URL. Disable activity tracking on unused integrations to avoid confusion. + + ## 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. +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**. @@ -51,11 +60,20 @@ If the automatic configuration fails for any reason, or if you prefer to set it ![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 +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` | + ![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** +10. Under **Signature Verification**, enable **Enable Signed Event Webhook**. +11. Click **Save**. ### Part 2: Add the signing key to Novu (Recommended) @@ -63,15 +81,30 @@ For enhanced security, you should add a signing key to verify that webhooks are 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. +3. Click the settings icon next to the webhook — 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. +5. Enable **Signed Webhook Verification** if it 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. +7. Return to your Novu SendGrid integration settings. +8. 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**. +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 -Your SendGrid integration is now manually configured to send activity data to Novu. \ No newline at end of file +`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](/platform/developer/webhooks/event-types#where-message-events-come-from) for details.