diff --git a/content/docs/platform/additional-resources/limits.mdx b/content/docs/platform/additional-resources/limits.mdx deleted file mode 100644 index 39472983b..000000000 --- a/content/docs/platform/additional-resources/limits.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: 'Limits' -description: 'System limits for Novu' -icon: 'Gauge' ---- - -import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; - -This document outlines the default limits for workflows and steps within workflows for new accounts. These limits are designed to ensure optimal performance and resource allocation. Users requiring custom limits can contact support for further assistance. - ---- - -## Workflow Limits - -**Maximum Number of Workflows**: 100 All accounts are set to a maximum of 100 workflows. This limit ensures efficient resource management and system performance. - -## Step Limits - -**Maximum Number of Steps per Workflow**: Each new workflow is limited to 20 steps. This safeguard ensures workflows remain manageable and performant. - -## Custom Limits - -If you need to increase the limits for workflows or steps, you can contact [support](mailto:support@novu.co) to discuss your needs. Custom limits may be granted based on usage requirements and system capacity. - ---- - -## FAQs - - - - Exceeding the default limit may result in restricted functionality or errors. Contact support to request a custom limit. - - - - Yes, custom step limits can be applied to individual workflows upon request. - - - - Custom limits may incur additional costs depending on the resources required. Support will provide details during the approval process. - - diff --git a/content/docs/platform/concepts/environments.mdx b/content/docs/platform/concepts/environments.mdx deleted file mode 100644 index f90e94821..000000000 --- a/content/docs/platform/concepts/environments.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: 'Environments' -description: 'Understanding and managing environments in Novu' -icon: 'GitFork' ---- - -Novu uses environments to separate your development and production workflows. When you create an account, you'll get two default environments: **Development** and **Production**. - -## Development environment - -Use the development environment to build and test new workflows, layouts, translations, and experiment with different configurations before publishing to other environments. - -## Production environment - -The Production environment is your live environment, sending notifications to real users. To ensure stability and prevent unintended changes, this environment is view-only for workflows, layouts, and translations. - -Changes are not made here directly but are pushed from the non production environment via the publishing process. - -## Custom Environments - -Custom environments are available in Team and Enterprise plans. - -Create custom environments to match your development workflow: - -1. Go to the [Environments page](https://dashboard.novu.co/environments) in Novu dashboard -2. Click on the **Create environment** button on the top right. -3. A menu will appear. Enter your preferred environment name. -4. Assign unique colors to easily distinguish between environments. - ![Publish changes](/images/developer-tools/create-environment.png) -5. Click on **Create environment** button on the bottom right. -6. New environment will be created and will be available in the environments list. - -## What's unique to each environment? - -Each environment has a mix of isolated resources and assets that can be published from Development. - -### Environment specific resources - -These resources are completely separate and unique to each environment. Data in one environment has no connection to data in another. They are: - -- Subscribers -- Topics -- Integrations (Provider credentials) -- API keys (application identifier and secret key) -- Activity feed -- Webhooks - -### Publishable assets - -These assets are managed centrally in the Development environment and then published to other environments. -- Workflows -- Layouts -- Translations - -### Environment Credentials - -Each environment has two unique identifiers: - -1. **Application Identifier** - - - Public ID for client-side apps - - Used with {``} - - Unique per environment - - Safe to expose in frontend code - -2. **API Secret Key** - - Used for backend API authentication - - Keep this secure and never expose publicly - - Different for each environment - -**Best Practice**: Configure these credentials in your application based on the active environment, similar to how you manage other service credentials. - -## Publishing changes to other environments - -Novu provides a publish mechanism that allows you to promote changes from your dvelopment environment to production or other custom environments. This process ensures that all changes are deliberate, reviewed, and deployed in a controlled manner. - -The publishing process bundles all modifications made to workflows, layouts, and translations since the last publish event. - -### How to publish changes - -After making modifications in your Development environment in the [Novu dashboard](https://dashboard.novu.co), you can promote them to another environment by following these steps: - -1. Ensure you are in the Development environment. All changes must originate from here. -2. Click the **Publish changes** button in the top right of the screen. - ![Publish changes](/images/developer-tools/publish-changes.png) -3. A list of available environments will appear. Select the environment you want to publish to. - ![Publish changes](/images/developer-tools/list-of-environment.png) -4. A menu will open showing all the availabl workflows. Select the checkboxes next to the workflows you want to publish. - ![Publish changes](/images/developer-tools/publish-changes-modal.png) -5. Click the publish button to publish the selected workflows to the selected environment. \ No newline at end of file diff --git a/content/docs/platform/developer/environments.mdx b/content/docs/platform/developer/environments.mdx new file mode 100644 index 000000000..d21f44fa9 --- /dev/null +++ b/content/docs/platform/developer/environments.mdx @@ -0,0 +1,89 @@ +--- +title: 'Environments' +description: 'Understanding and managing environments in Novu' +icon: 'GitFork' +--- + +Novu uses environments to separate your workflows and it's data. This lets you safely test changes, like a new workflow, in one environment before moving it to a live production environment. + +## Types of environments + +When you create a Novu account, you are provided with a development and production environment by default. You can also create custom environments (on certain plans) to match your team’s workflow. + +- **Development environment**: Use the development environment to build and test new workflows, layouts, translations, and experiment with different configurations before publishing to other environments. + +- **Production environment**: The production environment is used to send notifications to your subscribers. To ensure stability and prevent unintended changes, this environment is view-only for workflows, layouts, and translations. Changes are not made here directly, they are made from other environment and then published to this production environment. + +- **Custom environment**: Custom environments are only available on Team and Enterprise plans. You can use them to reflect your release process, for example, staging or QA. + +## Creating a custom environment + +To create a custom environment: + +1. Log in to the Novu dashboard. +2. Go to the [Environments page](https://dashboard.novu.co/environments) in the Novu dashboard. +3. Click **Create environment**. A menu appears. +4. A menu will appear. Enter your preferred environment name. +5. Assign unique colors to easily distinguish between environments. + ![Publish changes](/images/developer-tools/create-environment.png) +6. Click **Create environment**. + The new environment is created and is available in the environments list. + +## What's unique to each environment? + +Each environment in Novu has it's own isolated resources, while the development environment has assets that can be published to other environments. + +Each environment maintains some isolated set of resources, while you can share or promote other assets through publishing. + +### Environment-specific resources + +These resources are completely separate and unique to each environment. Data in one environment has no connection to data in another. They are: + +- Subscribers +- Topics +- Integrations (Provider credentials) +- API keys (application identifier and secret key) +- Activity feed +- Webhooks + +### Publishable assets + +These assets are managed centrally in the development environment and then published to other environments. +- Workflows +- Layouts +- Translations + +### Environment credentials + +Each environment has two unique identifiers: + +1. **Application Identifier** + + - Public ID for client-side apps + - Used with {``} + - Different for each environment + - Safe to expose in frontend code + +2. **API Secret Key** + - Used for backend API authentication + - Keep this secure and never expose publicly + - Different for each environment + +Configure these credentials in your application based on the active environment, similar to how you manage other service credentials. + +## Publishing changes to other environments + +Novu provides a publish mechanism that allows you to promote changes from your development environment to production or other custom environments. This process ensures that all changes are deliberate, reviewed, and deployed in a controlled manner. + +The publishing process bundles all modifications made to workflows, layouts, and translations since the last publish event. + +You can promote changes to other environments by following these steps: + +1. Ensure you are in the **Development** environment. All changes must originate from here. +2. Click **Publish changes**. A list of available environments appears. + ![Publish changes](/images/developer-tools/publish-changes.png) +3. Select the environment that you want to publish to. + ![Publish changes](/images/developer-tools/list-of-environment.png) +4. Select the checkboxes next to the workflows that you want to publish. A menu appears, showing all the available workflows. + ![Publish changes](/images/developer-tools/publish-changes-modal.png) +5. Click the publish button to publish the selected workflows to the selected environment. \ No newline at end of file diff --git a/content/docs/platform/developer/limits.mdx b/content/docs/platform/developer/limits.mdx new file mode 100644 index 000000000..4c4d9b1e7 --- /dev/null +++ b/content/docs/platform/developer/limits.mdx @@ -0,0 +1,36 @@ +--- +title: 'Limits' +description: 'System limits, quotas, and constraints for the Novu platform.' +icon: 'Gauge' +--- + +import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; + +Novu enforces default limits on specific resources and configurations. These limits apply to all new accounts by default. + + +Resource | Default limit | +| :--- | :--- | +| **Workflows** | You can create a maximum number of 100 workflows per account.| +| **Steps** | You can create a maximum number of 20 steps per workflow.| +| **Context** | You can create a maximum number of five contexts per workflow trigger.| + +## Custom limits + +If your project requires higher limits, you can request a custom configuration. [Contact support](mailto:support@novu.co) + +## FAQs + + + + Exceeding the default limit may result in restricted functionality or errors. [Contact support](mailto:support@novu.co) to request a custom limit. + + + + Yes, custom step limits can be applied to individual workflows upon request. + + + + Custom limits may incur additional costs depending on the resources required. [Support](mailto:support@novu.co) will provide details during the approval process. + + diff --git a/content/docs/platform/developer/meta.json b/content/docs/platform/developer/meta.json index ae5bff8da..f642184cf 100644 --- a/content/docs/platform/developer/meta.json +++ b/content/docs/platform/developer/meta.json @@ -1,3 +1,3 @@ { - "pages": ["webhooks"] + "pages": ["environments", "limits", "webhooks"] } diff --git a/content/docs/platform/developer/webhooks/index.mdx b/content/docs/platform/developer/webhooks/index.mdx new file mode 100644 index 000000000..78b824984 --- /dev/null +++ b/content/docs/platform/developer/webhooks/index.mdx @@ -0,0 +1,197 @@ +--- +title: 'Webhooks' +pageTitle: 'Webhooks' +description: 'Receive notifications when events occur in your Novu account' +--- + + +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. + +## How it works + +You provide Novu with a URL (endpoint), and we send a JSON payload to that URL whenever an event happens, such as a workflow update or message delivery. + +For example, if you want to receive updates at `https://api.yourservice.com/novu/webhook/`, you configure this as your endpoint. Your server should acknowledge receipt by returning a 2xx status code (200-299) within 15 seconds. + +Disable CSRF protection for your endpoint if the framework you use enables them by default. Also, verify the signature and timestamp when processing them. + +## How to add a webhook endpoint + +To start listening to messages, you must register your endpoint in the Novu dashboard. + +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. + ![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. +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. + ![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**. + +If your endpoint isn't ready, you can use tools like [Webhook.site](https://webhook.site/) or [RequestBin](https://requestbin.com/) to generate a temporary URL for testing. + + +### Advanced configuration + +When adding or editing an endpoint, you can utilize the advanced configuration option to fine-tune how Novu communicates with your server. + +- **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. + +### Testing endpoints + +After you've added an endpoint, you can test it to be sure it's working. To do this: +1. Click on the endpoint you want to test. +2. Click the **Testing** tab. +3. Select an event type you want to test with. + ![Testing endpoints](/images/developer-tools/testing-endpoints.png) +4. Click **Send Example**. + +After sending an example event, you can view the message payload, all of the message attempts, and whether it succeeded or failed. + +![After testing](/images/developer-tools/after-testing.png) + +## Verifying your webhooks signatures + +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. + +```tsx +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); +``` + +Check out the Svix webhook verification documentation, for more instructions and examples of how to verify signatures. + +## Recovery and resending failed messages + +If your service experiences downtime or if your endpoint was misconfigured, you can replay failed messages once you are back online. + +### Delivery attempts + +If Novu cannot deliver an event, it retries using exponential backoff. 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) + +For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt. + +You can find all the historical delivery attempts for each webhook endpoint in the webhook activity tab of that endpoint. +![Delivery attempts](/images/developer-tools/delivery-attempts.png) + +If your endpoint is unavailable, Novu keeps retrying according to the retry schedule. If all attempts fail for 5 days, the endpoint will be disabled and you have to manually re-enable it. + +### Resend a single failed event + +To resend an individual event: +1. Click the **Logs** tab and find the failed message you want to replay. +2. Under the **Webhook Attempts** section, Click the (**...**) icon + ![Resend single event](/images/developer-tools/resend-event.png) +3. Click **Resend** to attempt delivery again. + +### Recover all failed messages + +This operation causes all failed messages to a particular endpoint to be resent. To do this: +1. Click on the endpoint from the **Endpoints** tab. +2. Click the (**...**) icon. + ![Recover all failed messages](/images/developer-tools/recover.png) +3. Click **Recover failed messages**. +4. On the menu, select a time window to recover all failed messages from that period. For example, you can recover all fialed messages in the last 8 hours. + ![Recover all failed messages menu](/images/developer-tools/recover-menu.png) + + +### Replay missing messages + +This operation causes all messages that were never attempted for a particular endpoint to be resent. To do this: + +1. Click on the endpoint from the **Endpoints** tab. +2. Click the (**...**) icon. +3. Click **Replay missing messages**. +4. On the menu, select a time window to replay all failed messages from that period. For example, you can replay all missing messages from the last 8 hours that were never attempted. + ![Recover all failed messages menu](/images/developer-tools/replay-menu.png) + +## Managing webhooks endpoints + +### Enable or Disable an endpoint + +Endpoints can be manually enabled or disabled at any time. Novu also automatically disables an endpoint if all deliveries fail for 5 consecutive days. + +To enable or disable an endpoint: +1. Go to the webhook page of the Novu dashboard. +2. Find the endpoint you want to enable or disable from the list. +3. Click the (...) icon. + ![Disable or enable endpoints](/images/developer-tools/disable-endpoint.png) +4. Click **Disable Endpoint** or **Enable Endpoint** if the endpoint was previously disabled. + +### Delete an Endpoint + +Deleting an endpoint immediately stops all future delivery attempts and removes the configuration from your account. This action is permanent. + +To delete an endpoint: +1. Go to the webhook page of the Novu dashboard. +2. Find the endpoint you want to enable or disable from the list. +3. Click the (**...**) icon. +4. Click **Delete**. + +## Troubleshooting + +There are some common reasons why your webhook endpoint is failing: + +### Not using the raw payload body + +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. + +Verify the payload exactly as it was sent, byte-for-byte or string-for-string, to ensure accurate verification. + +### Sending the wrong response codes + +When Novu receives a response with a 2xx status code, it is interpreted as a successful delivery even if you indicate a failure in the response payload. Make sure to use the right response status codes so Novu knows when messages are supposed to succeed or fail. + +### Responses timing out + +Novu considers all messages that fails to send a response within 15 seconds as a failed message. + +If your endpoint is also processing complicated workflows, it may timeout and result in failed messages. In such cases, you can have your endpoint receive the message and add it to a queue to be processed asynchronously to avoid getting timed out. + +## Frequently asked questions + +### How do I secure my webhook endpoint? + +To secure your webhook endpoint, you should: + +1. Verify the webhook signature using the Svix 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 + + + +### 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. diff --git a/content/docs/platform/developer/webhooks/meta.json b/content/docs/platform/developer/webhooks/meta.json new file mode 100644 index 000000000..a43eec4b8 --- /dev/null +++ b/content/docs/platform/developer/webhooks/meta.json @@ -0,0 +1,6 @@ +{ + "icon": "Webhook", + "pages": ["event-types"], + "title": "Webhooks", + "description": "Learn about webhooks, how to set them up, and how to use them to receive real-time notifications about events in your account." +} diff --git a/content/docs/platform/additional-resources/webhooks.mdx b/content/docs/platform/developer/webhooks/webhooks.mdx similarity index 100% rename from content/docs/platform/additional-resources/webhooks.mdx rename to content/docs/platform/developer/webhooks/webhooks.mdx diff --git a/content/docs/platform/meta.json b/content/docs/platform/meta.json index 812d4a00a..93bad57c9 100644 --- a/content/docs/platform/meta.json +++ b/content/docs/platform/meta.json @@ -25,18 +25,20 @@ "workflow/contexts", "---Channels---", "...integrations", - "---Account---", - "account/authentication", - "account/roles-and-permissions", - "account/manage-members", - "account/billing", - "account/sso", "---SDKs---", "sdks/overview", "sdks/react", "sdks/javascript/index", "sdks/react-native", "sdks/server", + "---Developer---", + "...developer", + "---Account---", + "account/authentication", + "account/roles-and-permissions", + "account/manage-members", + "account/billing", + "account/sso", "---Additional Resources---", "additional-resources/glossary", "additional-resources/mcp", diff --git a/public/images/developer-tools/add-webhook.png b/public/images/developer-tools/add-webhook.png new file mode 100644 index 000000000..f9ec238eb Binary files /dev/null and b/public/images/developer-tools/add-webhook.png differ diff --git a/public/images/developer-tools/after-testing.png b/public/images/developer-tools/after-testing.png new file mode 100644 index 000000000..8cef736f6 Binary files /dev/null and b/public/images/developer-tools/after-testing.png differ diff --git a/public/images/developer-tools/delivery-attempts.png b/public/images/developer-tools/delivery-attempts.png new file mode 100644 index 000000000..67d8e58d2 Binary files /dev/null and b/public/images/developer-tools/delivery-attempts.png differ diff --git a/public/images/developer-tools/disable-endpoint.png b/public/images/developer-tools/disable-endpoint.png new file mode 100644 index 000000000..3994c5cb1 Binary files /dev/null and b/public/images/developer-tools/disable-endpoint.png differ diff --git a/public/images/developer-tools/recover-menu.png b/public/images/developer-tools/recover-menu.png new file mode 100644 index 000000000..7cb0ca5e9 Binary files /dev/null and b/public/images/developer-tools/recover-menu.png differ diff --git a/public/images/developer-tools/recover.png b/public/images/developer-tools/recover.png new file mode 100644 index 000000000..f74d47aa5 Binary files /dev/null and b/public/images/developer-tools/recover.png differ diff --git a/public/images/developer-tools/replay-menu.png b/public/images/developer-tools/replay-menu.png new file mode 100644 index 000000000..df0514105 Binary files /dev/null and b/public/images/developer-tools/replay-menu.png differ diff --git a/public/images/developer-tools/resend-event.png b/public/images/developer-tools/resend-event.png new file mode 100644 index 000000000..4c1144df3 Binary files /dev/null and b/public/images/developer-tools/resend-event.png differ diff --git a/public/images/developer-tools/testing-endpoints.png b/public/images/developer-tools/testing-endpoints.png new file mode 100644 index 000000000..586cbffce Binary files /dev/null and b/public/images/developer-tools/testing-endpoints.png differ diff --git a/public/images/developer-tools/webhook-integrations.png b/public/images/developer-tools/webhook-integrations.png new file mode 100644 index 000000000..608931b78 Binary files /dev/null and b/public/images/developer-tools/webhook-integrations.png differ