From f3e0ebfea36a0b8b9a54486624a633bbe5872ab2 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Fri, 30 Jan 2026 12:39:03 -0700 Subject: [PATCH 01/23] Add Event Notifications (Beta) documentation Migrate Event Notifications documentation from Alpha Google Doc to repo in preparation for Beta launch. This completes the "Before Beta Launch" and "Beta Launch Week" documentation tasks. New documentation pages: - event-notifications.mdx: Main landing page with overview, comparison table, event types, use cases, and prerequisites - event-notifications-create.mdx: Step-by-step guide for creating notification subscriptions with filter configuration and troubleshooting - event-notifications-manage.mdx: Instructions for viewing, editing, deleting, and managing notification subscriptions - event-notifications-webhooks.mdx: Technical webhook documentation with HMAC verification, code examples, Slack integration, and debugging Updates to existing documentation: - instance-notifications-config.mdx: Updated title to include "(Legacy)" label, added deprecation warning banner, and cross-links to new docs - sidebars.js: Added new Event Notifications pages to navigation under "Insights and Telemetry" section Content exclusions (as requested): - Omitted "Available events and filters" maintenance section (too hard to maintain; kept high-level event types on main page) - Removed "Types of feedback" section (Alpha-specific) - Removed Alpha-specific language and feature flag references Screenshots deferred: - Added TODO comments for future screenshots when UI stabilizes - Screenshot capture planned for post-UI-stabilization phase This migration enables sunsetting the Google Doc as the source of truth for Event Notifications documentation. Co-Authored-By: Claude Sonnet 4.5 --- docs/vendor/event-notifications-create.mdx | 210 ++++++++ docs/vendor/event-notifications-manage.mdx | 243 +++++++++ docs/vendor/event-notifications-webhooks.mdx | 491 ++++++++++++++++++ docs/vendor/event-notifications.mdx | 172 ++++++ docs/vendor/instance-notifications-config.mdx | 16 +- sidebars.js | 4 + 6 files changed, 1134 insertions(+), 2 deletions(-) create mode 100644 docs/vendor/event-notifications-create.mdx create mode 100644 docs/vendor/event-notifications-manage.mdx create mode 100644 docs/vendor/event-notifications-webhooks.mdx create mode 100644 docs/vendor/event-notifications.mdx diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx new file mode 100644 index 0000000000..63929b16b7 --- /dev/null +++ b/docs/vendor/event-notifications-create.mdx @@ -0,0 +1,210 @@ +# Create Event Notification Subscriptions (Beta) + +:::note +Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +::: + +This topic describes how to create event notification subscriptions in the Replicated Vendor Portal. + +## Overview + +You can create notification subscriptions from scratch to receive alerts when specific events occur. Each subscription can be customized with filters to target exactly the events that matter to your workflow, and can be delivered via email or webhook. + +## Prerequisites + +Before creating event notification subscriptions, ensure you have: + +- **RBAC Permissions**: Appropriate permissions to create notifications. See [RBAC Permissions](event-notifications#prerequisites) in _Event Notifications (Beta)_. +- **Email or Webhook URL**: A destination for your notifications (your email address or a webhook URL for integrations like Slack). + +For webhook delivery: +- A webhook endpoint URL that can receive POST requests +- (Optional) A signing secret for HMAC signature verification + +## Create a Notification from Scratch + +To create a new notification subscription: + +1. Navigate to **Notifications** in the Vendor Portal + +2. Click **"New Notification"** or **"Create Notification"** + +3. **Select an event type** from the dropdown: + - Events are organized by category (Instance, Release, Customer, Channel, Support) + - Use the search box to quickly find event types + - Each event displays its description to help you choose + + + +4. **Configure filters** for the event type: + - Available filters depend on the event type selected + - Most filters support dropdown selection from your existing resources + - Some filters support multiselect (e.g., License Type, Customer) + - Text filters allow pattern matching (e.g., Entitlement Filter) + - Leave filters empty to match all values + + **Common Filters:** + - **Application**: Filter by specific application + - **Channel**: Filter by release channel (Stable, Beta, Unstable, etc.) + - **Customer**: Filter by specific customer(s) + - **License Type**: Filter by license type (Trial, Paid, Community, Development) + - **Instance**: Filter by specific instance (for instance events) + - **Number of Versions Behind**: Threshold for version behind alerts + - **Days Until Expiry**: Threshold for license expiration warnings + + + +5. **Choose your notification delivery method**: + + ### Email Delivery + - Enter an email address + - Email addresses other than your Vendor Portal account email require verification (see [Email Verification](#email-verification) below) + + ### Webhook Delivery + - Enter a webhook URL + - (Optional) Enter a signing secret for HMAC signature verification + - See [Event Notification Webhooks (Beta)](event-notifications-webhooks) for technical details + + + +6. (Optional) **Name your notification** for easy identification + - Use descriptive names like "Trial License Expiration Alerts" or "Acme Corp Support Bundles" + - Names help you quickly identify subscriptions in the list view + +7. Click **"Create Notification"** to activate + +Your notification subscription is now active and will begin matching events based on your configured filters. + +## Email Verification {#email-verification} + +When sending to an email address other than the one associated with your Vendor Portal user account, you must first validate that email before notifications can be sent. + +### Verification Process + +1. After creating a notification with an unverified email address, a verification email will be sent to that address +2. The notification subscription will be created but remain inactive until verified +3. To complete verification, you have two options: + + **Option 1: Email Link** + - Open the verification email + - Click the validation link in the email + - You must be logged into Vendor Portal in your browser to validate + + **Option 2: Verification Code** + - Copy the verification code from the email + - Navigate to **Notifications** in the Vendor Portal + - Edit the notification subscription + - Enter the verification code + - Save the notification + +4. Once verified, the notification subscription will become active and begin sending notifications + +:::note +You must be logged into Vendor Portal to validate email addresses. +::: + +## AI-Assisted Notification Builder (Optional) + +Vendor Portal includes an optional AI-assisted notification builder to help you quickly set up subscriptions. + +To use the AI builder: + +1. Click **"Create with AI"** for guided notification setup +2. Describe in natural language what you want to be notified about + - Example: "Notify me when trial customers upload support bundles" + - Example: "Alert me when instances fall more than 3 versions behind on the Stable channel" +3. The AI will suggest the appropriate event type and filters based on your description +4. Review and adjust the AI's suggestions before creating +5. Proceed with the standard creation workflow + +:::note +The AI builder has context of pre-defined event types and filters, but cannot create new event types or filters beyond what's available in the system. +::: + +## Filter Logic + +Understanding how filters work will help you create effective notification subscriptions. + +### Basic Filter Behavior + +- **No filters specified**: The notification will match **all events** for that event type +- **One or more filters specified**: The event must match **all specified filters** to trigger the notification (AND logic) +- **Multi-select filters**: If a filter contains multiple selected values, the event must match **any** of the selected values within that filter to trigger the notification (OR logic within the filter) + +### Examples + +**Example 1: Single Filter** +- Event Type: Customer Created +- Filter: License Type = Trial +- **Result**: Notification triggers for all trial customer creations + +**Example 2: Multiple Filters (AND logic)** +- Event Type: Instance Upgraded +- Filter: Application = "MyApp" +- Filter: Channel = "Stable" +- **Result**: Notification triggers only when instances of MyApp on the Stable channel are upgraded + +**Example 3: Multi-Select Filter (OR logic within filter)** +- Event Type: Customer License Expiring +- Filter: Application = "MyApp" +- Filter: License Type = Trial, Paid (both selected) +- **Result**: Notification triggers when either trial OR paid customer licenses for MyApp are expiring + + + +## Testing Your Subscription + +After creating a notification subscription, verify that it works as expected: + +1. Trigger the event condition in a development or test environment + - For example, create a test customer or upload a support bundle +2. Check your email inbox or webhook endpoint for the notification +3. Review the notification history in the Vendor Portal: + - Navigate to **Notifications** > **History** + - Verify the event was captured and delivery was successful +4. If notifications aren't arriving: + - Verify email address is validated (check for verification email) + - Check that filters aren't too restrictive + - Review notification history for delivery errors + - For webhooks, see [Debugging Webhooks](event-notifications-webhooks#debugging) in _Event Notification Webhooks (Beta)_ + +## Troubleshooting + +### Notification Not Triggering + +If your notification subscription isn't triggering when expected: + +- **Check filters**: Ensure your filters aren't too restrictive and that the event meets all filter conditions +- **Verify subscription is active**: Inactive or disabled subscriptions won't trigger +- **Check email verification**: Unverified email addresses will block notifications from being sent +- **Review notification history**: Look for attempted deliveries and error messages + +### Email Not Received + +If you created a notification but aren't receiving emails: + +- **Check spam folder**: Notification emails may be filtered by email clients +- **Verify email address**: Ensure the email address is correct and has been verified +- **Check notification history**: Verify the notification was triggered and email delivery was attempted +- **Check your RBAC permissions**: Ensure you have `team/notifications/events/read` permission to view history + +### Webhook Not Receiving Notifications + +If your webhook endpoint isn't receiving notifications: + +- **Verify webhook URL**: Ensure the URL is correct and publicly accessible +- **Check webhook endpoint logs**: Verify your endpoint is responding with 2xx status codes +- **Test webhook manually**: Use a tool like `curl` to test your endpoint +- **Review notification history**: Check for delivery errors and retry attempts +- See [Event Notification Webhooks (Beta)](event-notifications-webhooks) for detailed webhook troubleshooting + +## Next Steps + +- [Manage Event Notification Subscriptions (Beta)](event-notifications-manage) - View, edit, and delete subscriptions +- [Event Notification Webhooks (Beta)](event-notifications-webhooks) - Configure webhooks for integrations like Slack +- [Event Notifications (Beta)](event-notifications) - Overview and available event types + +## Related Topics + +- [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data +- [Custom RBAC Policies](team-management-rbac-configuring) - Configuring custom RBAC policies for notifications diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx new file mode 100644 index 0000000000..3517ff29c1 --- /dev/null +++ b/docs/vendor/event-notifications-manage.mdx @@ -0,0 +1,243 @@ +# Manage Event Notification Subscriptions (Beta) + +:::note +Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +::: + +This topic describes how to view, edit, disable, and delete event notification subscriptions in the Replicated Vendor Portal. + +## Overview + +The Notifications page in the Vendor Portal provides visibility into both personal and team notification subscriptions, as well as a complete history of notification events. You can manage your own subscriptions and, if you have the appropriate permissions, view and manage team subscriptions. + +## Viewing Notification Subscriptions + +The Notifications list page provides three main views: + +### My Notifications + +Shows only notification subscriptions you created, giving you quick access to manage your personal monitoring setup. + +To view your notifications: + +1. Navigate to **Notifications** in the Vendor Portal +2. Select the **My Notifications** tab +3. View the list of your active and inactive subscriptions + + + +### Team Notifications + +Shows all notification subscriptions created by anyone on your team. This view is useful for understanding what monitoring is in place across the organization. + +To view team notifications: + +1. Navigate to **Notifications** in the Vendor Portal +2. Select the **Team Notifications** tab +3. View all subscriptions created by team members + +**Permissions:** +- **Team admins** can manage (edit/delete) any team member's notifications +- **Non-admin users** can view team notifications but cannot modify subscriptions created by others + + + +### History + +Shows all triggered notification events for the selected time period. You can filter the history to show only your notifications or filter by a specific configured notification. + +To view notification history: + +1. Navigate to **Notifications** in the Vendor Portal +2. Select the **History** tab +3. Use the filters to narrow results: + - Filter by time period + - Filter to "My Notifications Only" + - Filter to a specific notification subscription + + + +## Viewing Notification Event Details + +Each notification event in the history view can be expanded to show detailed information: + +To view event details: + +1. Navigate to **Notifications** > **History** +2. Find the event you want to inspect +3. Click to expand the event row + +Event details include: +- List of all events that matched this notification's filters +- Timestamp when each event occurred +- Event details (customer, instance, application, etc.) +- Delivery status (Sent, Failed, Pending) +- For failures: Error message explaining why delivery failed + +This information is helpful for troubleshooting notification delivery issues and understanding which events are triggering your subscriptions. + +## Editing an Existing Notification + +To modify a notification subscription: + +1. Navigate to **Notifications** in the Vendor Portal + +2. Find the notification you want to edit in the list: + - Use the **My Notifications** tab for your subscriptions + - Use the **Team Notifications** tab to find any team member's subscription (if you're a team admin) + +3. Click the **Edit** icon or **"Edit"** button for that notification + +4. The notification form will open with all current settings populated + +5. Make your desired changes: + - Modify filters to broaden or narrow the scope + - Change the delivery method or destination + - Update the notification name + - Pause/unpause the notification + +6. Click **"Save Changes"** to update + + + +**Important notes:** +- Editing a notification does not affect past events already sent +- Changes apply immediately to future events +- You can only edit notifications you created, unless you're a team admin with permissions to manage all team notifications + +## Disabling a Notification (Pause) + +To temporarily stop a notification without deleting it: + +1. Navigate to **Notifications** in the Vendor Portal +2. Find the notification in the list +3. Click the **Edit** button +4. Toggle the notification to **Disabled** or **Paused** state +5. Save your changes + +When a notification is disabled: +- It stops triggering for new events +- The subscription configuration is preserved +- Historical event data remains available +- You can re-enable it at any time by editing and toggling back to active + +## Deleting an Existing Notification + +To permanently remove a notification subscription: + +1. Navigate to **Notifications** in the Vendor Portal + +2. Find the notification you want to delete in the list + +3. Click the **Delete** icon or **"Delete"** button for that notification + +4. Confirm the deletion in the prompt + +5. The notification is permanently removed + +**Important notes:** +- Deleting a notification is permanent and cannot be undone +- No further notifications will be sent for this subscription +- Historical event data for the notification is preserved and remains viewable in the History view +- You can only delete notifications you created, unless you're a team admin + +## Viewing Event History for a Specific Notification + +Each notification maintains a history of when it triggered and what events matched: + +1. Navigate to **Notifications** in the Vendor Portal +2. Find the notification in the list (either **My Notifications** or **Team Notifications**) +3. Click the **"View History"** button for that notification + +This filtered view shows only events that matched this specific notification subscription, making it easier to understand the notification's behavior and troubleshoot any issues. + +## Understanding Notification Permissions + +Event Notifications uses team-scoped RBAC permissions to control access. Your ability to view and manage notifications depends on your role: + +### Admin Role +- Can manage any team-created notifications in addition to their own +- Can modify, delete, and turn off/on any notification +- Full access to all notification features + +### Read Only Role +- Cannot create notifications +- Can view all team notifications and their event history +- No modification permissions + +### Other Non-Admin Roles with Write Access +(Examples: Support Engineer, Sales, Custom roles) +- Can create and modify their own notifications +- Broader team notifications are viewable but not modifiable (read-only) +- Cannot edit or delete subscriptions created by other team members + +:::note +When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. +::: + +## Notification List Filtering and Sorting + +The Notifications list page supports filtering and sorting to help you find specific subscriptions: + +**Available filters:** +- Active vs. Inactive subscriptions +- Event type +- Delivery method (Email or Webhook) +- Created by (for Team Notifications view) + +**Sorting options:** +- Name (A-Z or Z-A) +- Created date (newest or oldest first) +- Last triggered (most recent or least recent) + +Use these tools to quickly locate and manage your notification subscriptions. + +## Troubleshooting Notification Delivery + +### Viewing Delivery Status + +To check if notifications are being delivered successfully: + +1. Navigate to **Notifications** > **History** +2. Look at the **Delivery Status** column for each event: + - **Sent**: Notification was successfully delivered + - **Failed**: Delivery failed (expand row to see error message) + - **Pending**: Delivery is in progress or queued + +### Common Delivery Issues + +**Email not verified:** +- Check if the email address requires verification +- Look for a verification email in your inbox +- Edit the notification to enter the verification code + +**Filters too restrictive:** +- Review your filter configuration +- Check that events are actually matching your criteria +- Temporarily broaden filters to test + +**Webhook endpoint issues:** +- Verify webhook URL is correct and accessible +- Check that your endpoint returns 2xx status codes +- See [Event Notification Webhooks (Beta)](event-notifications-webhooks) for webhook troubleshooting + +**RBAC permissions:** +- Verify you have the necessary permissions to create and manage notifications +- Contact your team admin if you need additional permissions + +## Bulk Management (Future) + +:::note +Bulk management features such as bulk enable/disable and bulk delete are planned for a future release. +::: + +## Next Steps + +- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Create new notification subscriptions +- [Event Notification Webhooks (Beta)](event-notifications-webhooks) - Configure webhooks for integrations like Slack +- [Event Notifications (Beta)](event-notifications) - Overview and available event types + +## Related Topics + +- [Custom RBAC Policies](team-management-rbac-configuring) - Configuring custom RBAC policies for notifications +- [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx new file mode 100644 index 0000000000..50b97e227c --- /dev/null +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -0,0 +1,491 @@ +# Event Notification Webhooks (Beta) + +:::note +Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +::: + +This topic describes how to configure and use webhooks for Event Notifications, including webhook payload structure, HMAC signature verification, and integration with services like Slack. + +## Overview + +Webhooks allow you to receive Event Notifications as HTTP POST requests to an endpoint you control. This enables integration with services like Slack, PagerDuty, custom monitoring systems, and other tools that support webhook integrations. + +Event Notifications webhooks include: +- JSON payload with event data +- HMAC-SHA256 signature for verification +- Automatic retries with exponential backoff +- Delivery attempt tracking + +## Configuring Webhook URLs + +To configure a webhook for Event Notifications: + +1. **Prepare your webhook endpoint:** + - Ensure your endpoint can receive HTTP POST requests + - Endpoint must be publicly accessible (or use a secure tunnel for testing) + - Endpoint should respond with a 2xx status code (200-299) for successful delivery + - Response time should be under 5 seconds + +2. **Create a notification subscription with webhook delivery:** + - Navigate to **Notifications** > **Create Notification** + - Select your event type and configure filters + - Choose **Webhook** as the delivery method + - Enter your webhook URL + - (Optional but recommended) Enter a signing secret for HMAC verification + +3. **Test your webhook:** + - Trigger a test event to verify webhook delivery + - Check your endpoint logs for incoming requests + - Verify the payload structure matches your expectations + +See [Create Event Notification Subscriptions (Beta)](event-notifications-create) for detailed instructions on creating subscriptions. + +## Webhook Payload Structure + +Event Notifications webhooks deliver a JSON payload with the following structure: + +```json +{ + "event": "customer.created", + "timestamp": "2026-01-25T22:48:32Z", + "text": "A new customer has been created.\n\nCustomer: Testy McTestface\nCustomer ID: 38ljzNKNZZSIp3bUQYSPzJUUBpd\nApplication: Demo\nChannel: Stable\nLicense Type: trial\nExpiration: 2026-02-24\nCreated at: 2026-01-25 22:48:32 UTC\n\nView customer: https://vendor.replicated.com/apps/demo-jaybird/customer/38ljzNKNZZSIp3bUQYSPzJUUBpd", + "data": { + "app_id": "34LgWqPkIlmhPDhvQVrbWcRwvLW", + "team_id": "CKUTNRX16FghU69v_RjZ1Q1EFXBcQBMZ", + "app_name": "Demo", + "app_slug": "demo-jaybird", + "eventType": "customer.created", + "channel_id": "34LgWuB1oCNbdLV6BbeepUSAEA6", + "created_at": "2026-01-25T22:48:32.391894468Z", + "event_type": "customer.created", + "expires_at": "2026-02-24T22:47:37Z", + "customer_id": "38ljzNKNZZSIp3bUQYSPzJUUBpd", + "channel_name": "Stable", + "license_type": "trial", + "customer_name": "Testy McTestface" + } +} +``` + +### Payload Fields + +| Field | Type | Description | +|-------|------|-------------| +| `event` | string | Event type identifier (e.g., "customer.created", "instance.upgraded") | +| `timestamp` | string | ISO 8601 timestamp when the event occurred | +| `text` | string | Human-readable text description of the event, formatted for easy reading | +| `data` | object | Event-specific data containing detailed information about the event | + +The `data` object contains fields specific to each event type. Common fields include: +- `app_id` - Application identifier +- `team_id` - Team identifier +- `app_name` - Application name +- `app_slug` - Application slug (URL-safe identifier) +- `event_type` - Event type identifier +- Additional fields specific to the event type (customer_id, instance_id, channel_id, etc.) + +## Webhook Signing (HMAC-SHA256) + +Event Notifications webhooks include an HMAC-SHA256 signature for verification. This allows you to verify that webhook requests are genuinely from Replicated and have not been tampered with. + +### How Signing Works + +When you configure a webhook with a signing secret: + +1. Replicated generates an HMAC-SHA256 signature of the webhook payload using your secret +2. The signature is sent in the `X-Replicated-Signature` HTTP header +3. Your endpoint can verify the signature to ensure authenticity + +### Signature Header Format + +The `X-Replicated-Signature` header contains the signature in the following format: + +``` +X-Replicated-Signature: sha256= +``` + +Example: +``` +X-Replicated-Signature: sha256=5d7f8e9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e +``` + +## Verifying Webhook Signatures + +To verify webhook signatures in your endpoint, follow these steps: + +### Step 1: Extract the Signature + +Extract the signature from the `X-Replicated-Signature` header: + +```javascript +const signatureHeader = req.headers['x-replicated-signature']; +const signature = signatureHeader.replace('sha256=', ''); +``` + +### Step 2: Compute the Expected Signature + +Compute the HMAC-SHA256 signature of the raw request body using your signing secret: + +```javascript +const crypto = require('crypto'); + +const hmac = crypto.createHmac('sha256', signingSecret); +hmac.update(requestBody); // Use the raw request body string +const expectedSignature = hmac.digest('hex'); +``` + +### Step 3: Compare Signatures + +Use a constant-time comparison to prevent timing attacks: + +```javascript +const crypto = require('crypto'); + +function verifySignature(signature, expectedSignature) { + return crypto.timingSafeEqual( + Buffer.from(signature, 'hex'), + Buffer.from(expectedSignature, 'hex') + ); +} + +if (!verifySignature(signature, expectedSignature)) { + // Signature verification failed - reject the request + return res.status(401).send('Invalid signature'); +} + +// Signature verified - process the webhook +``` + +### Complete Verification Example (Node.js/Express) + +```javascript +const express = require('express'); +const crypto = require('crypto'); + +const app = express(); +const SIGNING_SECRET = process.env.WEBHOOK_SIGNING_SECRET; + +app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => { + // Extract signature from header + const signatureHeader = req.headers['x-replicated-signature']; + if (!signatureHeader) { + return res.status(401).send('Missing signature header'); + } + + const signature = signatureHeader.replace('sha256=', ''); + + // Compute expected signature + const hmac = crypto.createHmac('sha256', SIGNING_SECRET); + hmac.update(req.body); // Raw body buffer + const expectedSignature = hmac.digest('hex'); + + // Verify signature + try { + if (!crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expectedSignature, 'hex'))) { + return res.status(401).send('Invalid signature'); + } + } catch (err) { + return res.status(401).send('Invalid signature'); + } + + // Signature verified - parse and process webhook + const payload = JSON.parse(req.body.toString()); + console.log('Received event:', payload.event); + console.log('Event data:', payload.data); + + // Process the event... + + res.status(200).send('OK'); +}); + +app.listen(3000, () => console.log('Webhook server listening on port 3000')); +``` + +### Verification Example (Python/Flask) + +```python +from flask import Flask, request, jsonify +import hmac +import hashlib +import os + +app = Flask(__name__) +SIGNING_SECRET = os.environ.get('WEBHOOK_SIGNING_SECRET') + +@app.route('/webhook', methods=['POST']) +def webhook(): + # Extract signature from header + signature_header = request.headers.get('X-Replicated-Signature') + if not signature_header: + return 'Missing signature header', 401 + + signature = signature_header.replace('sha256=', '') + + # Compute expected signature + raw_body = request.get_data() + expected_signature = hmac.new( + SIGNING_SECRET.encode('utf-8'), + raw_body, + hashlib.sha256 + ).hexdigest() + + # Verify signature + if not hmac.compare_digest(signature, expected_signature): + return 'Invalid signature', 401 + + # Signature verified - parse and process webhook + payload = request.get_json() + print(f"Received event: {payload['event']}") + print(f"Event data: {payload['data']}") + + # Process the event... + + return 'OK', 200 + +if __name__ == '__main__': + app.run(port=3000) +``` + +## Integrating with Slack + +To send Event Notifications to a Slack channel using webhooks: + +1. **Create a Slack incoming webhook:** + - Go to your Slack workspace settings + - Navigate to **Apps** > **Incoming Webhooks** + - Click **Add to Slack** + - Select the channel where you want to receive notifications + - Copy the webhook URL + + For detailed instructions, see the [Slack documentation on incoming webhooks](https://api.slack.com/messaging/webhooks). + +2. **Create an Event Notification subscription:** + - Navigate to **Notifications** > **Create Notification** in the Vendor Portal + - Select your event type and configure filters + - Choose **Webhook** as the delivery method + - Paste your Slack webhook URL + - (Optional) Add a signing secret if you want to verify signatures + +3. **Test the integration:** + - Trigger a test event to verify Slack notifications + - Check your Slack channel for the notification message + +The `text` field in the webhook payload is automatically formatted for readability in Slack and other chat tools. + +## Delivery Retries and Timeouts + +Event Notifications automatically retries failed webhook deliveries to ensure reliability. + +### Retry Behavior + +- **Initial delivery attempt:** Made immediately when the event occurs +- **Retry policy:** Exponential backoff with up to 8 retry attempts +- **Timeout:** Each delivery attempt times out after 5 seconds +- **Retry schedule:** Approximately 1m, 2m, 4m, 8m, 16m, 32m, 64m, 128m after initial failure + +### Successful Delivery + +A webhook delivery is considered successful when your endpoint: +- Responds with an HTTP status code in the 2xx range (200-299) +- Responds within 5 seconds + +### Failed Delivery + +A webhook delivery is considered failed when: +- Your endpoint responds with a non-2xx status code +- The request times out (exceeds 5 seconds) +- A network error occurs (endpoint unreachable, DNS failure, etc.) + +After all retry attempts are exhausted, the notification is marked as permanently failed and can be viewed in the notification history. + +## Debugging Webhooks {#debugging} + +### Viewing Webhook Delivery History + +To debug webhook delivery issues: + +1. Navigate to **Notifications** > **History** +2. Find the event you're investigating +3. Expand the event row to see: + - Delivery status (Sent, Failed, Pending) + - Delivery attempts and timestamps + - Error messages for failed attempts + - Response status codes from your endpoint + +### Common Webhook Issues + +**Issue: Webhooks not being received** +- Verify webhook URL is correct and publicly accessible +- Check firewall rules and network configuration +- Test endpoint manually with `curl` or Postman +- Review webhook delivery history for error messages + +**Issue: Signature verification failing** +- Ensure you're using the raw request body (not parsed JSON) +- Verify signing secret matches what you configured in the notification +- Check that you're extracting the signature from the correct header +- Use the verification code examples above as a reference + +**Issue: Endpoint timing out** +- Optimize endpoint response time (should be under 5 seconds) +- Process webhooks asynchronously (return 200 immediately, process in background) +- Add logging to identify slow operations + +**Issue: Duplicate webhooks received** +- Implement idempotency using the event timestamp and event type +- Store processed event IDs to prevent duplicate processing +- Handle retries gracefully in your application logic + +### Testing Webhooks Locally + +To test webhooks during development: + +1. **Use a tunnel service** like ngrok to expose your local endpoint: + ```bash + ngrok http 3000 + ``` + +2. **Use the ngrok URL** as your webhook URL in the notification configuration: + ``` + https://abc123.ngrok.io/webhook + ``` + +3. **Trigger test events** and watch the ngrok dashboard or your application logs + +## Security Best Practices + +### Always Verify Signatures + +- Always configure a signing secret when creating webhook subscriptions +- Always verify HMAC signatures in your endpoint before processing webhooks +- Reject requests with invalid or missing signatures + +### Use HTTPS Endpoints + +- Always use HTTPS webhook URLs in production +- Never use HTTP (unencrypted) endpoints for sensitive data + +### Implement Rate Limiting + +- Add rate limiting to your webhook endpoint to prevent abuse +- Consider implementing exponential backoff for retries in your application + +### Store Secrets Securely + +- Never hardcode signing secrets in your application code +- Use environment variables or a secrets management system +- Rotate signing secrets periodically + +### Process Webhooks Asynchronously + +- Return HTTP 200 immediately upon receiving webhooks +- Process webhook data in a background job or queue +- This prevents timeouts and improves reliability + +### Implement Idempotency + +- Use event timestamps and IDs to detect duplicate webhook deliveries +- Store processed event IDs to prevent duplicate processing +- Handle retries gracefully without side effects + +## Webhook Payload Examples by Event Type + +### Instance Events + +**Instance Created:** +```json +{ + "event": "instance.created", + "timestamp": "2026-01-30T10:15:32Z", + "text": "A new instance has been created...", + "data": { + "instance_id": "abc123", + "customer_id": "xyz789", + "app_name": "MyApp", + "channel_name": "Stable" + } +} +``` + +**Instance Upgraded:** +```json +{ + "event": "instance.upgraded", + "timestamp": "2026-01-30T10:20:45Z", + "text": "Instance upgraded to version 1.2.3...", + "data": { + "instance_id": "abc123", + "customer_id": "xyz789", + "version_label": "1.2.3", + "app_name": "MyApp" + } +} +``` + +### Release Events + +**Release Promoted:** +```json +{ + "event": "release.promoted", + "timestamp": "2026-01-30T11:00:00Z", + "text": "Release 1.2.3 promoted to Stable channel...", + "data": { + "release_sequence": 42, + "version_label": "1.2.3", + "channel_name": "Stable", + "app_name": "MyApp" + } +} +``` + +### Customer Events + +**Customer License Expiring:** +```json +{ + "event": "customer.license_expiring", + "timestamp": "2026-01-30T08:00:00Z", + "text": "Customer license expiring in 7 days...", + "data": { + "customer_id": "xyz789", + "customer_name": "Acme Corp", + "expires_at": "2026-02-06T00:00:00Z", + "days_until_expiry": 7, + "license_type": "trial" + } +} +``` + +### Support Events + +**Support Bundle Uploaded:** +```json +{ + "event": "supportbundle.uploaded", + "timestamp": "2026-01-30T14:30:00Z", + "text": "Support bundle uploaded by Acme Corp...", + "data": { + "bundle_id": "bundle123", + "customer_id": "xyz789", + "customer_name": "Acme Corp", + "instance_id": "abc123", + "app_name": "MyApp" + } +} +``` + +:::note +Payload structure varies by event type. The `data` object contains fields specific to each event. Use the webhook history view to inspect actual payloads for your events. +::: + +## Next Steps + +- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Create webhook subscriptions +- [Manage Event Notification Subscriptions (Beta)](event-notifications-manage) - View webhook delivery history +- [Event Notifications (Beta)](event-notifications) - Overview and available event types + +## Related Topics + +- [Slack Incoming Webhooks Documentation](https://api.slack.com/messaging/webhooks) - Setting up Slack webhooks +- [HMAC Verification Best Practices](https://en.wikipedia.org/wiki/HMAC) - Understanding HMAC signatures diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx new file mode 100644 index 0000000000..4eb7cc75fe --- /dev/null +++ b/docs/vendor/event-notifications.mdx @@ -0,0 +1,172 @@ +# Event Notifications (Beta) + +:::note +Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +::: + +The ability to set up notifications for key events of interest within the Replicated Vendor Portal can help you proactively manage and prevent issues across your customer instances, releases, support bundles, and more. + +## Overview + +Event Notifications allow you to subscribe to specific events and receive alerts via email or webhook. You can create highly targeted notifications using filters to focus on the events that matter most to your workflow. + +Event types available are predefined, but these events can cover a broad range of use cases by leveraging available filtering conditions on a given event. + +Events are queued to SQS for reliable processing and notifications are matched against event filters in real-time. Email notifications are sent via the configured email service, and webhook notifications include HMAC signatures for verification. + +## Key Differences from Legacy Instance Notifications + +Event Notifications offers significant improvements over the legacy [Instance Notifications (Legacy)](instance-notifications-config) system: + +- **More event types available**: Including customer events, support bundle events, release events, channel events, and more—not just instance events +- **More fine-grained alert customizability**: Improved filtering options let you target exactly what matters +- **Flexible routing**: Route each notification to different individual or team alias email addresses or webhook payloads (for integrations such as Slack) +- **Notification history**: View a complete history of event notifications sent +- **Better access control**: Control over your individual notification configurations with visibility into broader team notifications configured + +## Comparison: Legacy vs. Event Notifications (Beta) + +| Feature | Legacy Instance Notifications | Event Notifications (Beta) | +|---------|------------------------------|---------------------------| +| **Event Types** | 3 types (App Status, System Events, Custom Metrics) | 19+ types across 6 categories | +| **Scope** | Per-instance subscriptions | Team-wide with flexible filtering | +| **Delivery** | Slack (team webhook) + Email (user) | Email + Generic webhooks | +| **Filtering** | Instance-level only | Multi-field filters (app, customer, channel, etc.) | +| **Permissions** | User-scoped | Team-scoped RBAC | +| **Webhook Security** | Basic | HMAC-SHA256 signing | +| **Notification History** | Minimal | Full delivery attempt tracking with event details | +| **Status** | Maintenance mode | Active development | + +## Available Event Types + +Event Notifications initially supports the following high-level event types. Each event type can be further refined using filters to match your specific needs. + +### Instance Events +- **Instance Created** - When a new instance is created +- **Instance Upgraded** - When an instance upgrades to a new release version +- **Instance Version Behind** - When an instance falls behind by a specified number of versions +- **Instance Inactive** - When an instance has not reported in for 24 hours (declared "Inactive") + +### Release Events +- **Release Created** - When a new release is created +- **Release Promoted** - When a release is promoted to a channel +- **Release Demoted (Unpublished)** - When a release is demoted from a channel +- **Release Assets Downloaded** - When a release asset (such as a Helm chart or .tgz bundle) is pulled by a customer + +### Customer Events +- **Customer Created** - When a new customer is created +- **Customer Updated** - When a customer's details or license is updated +- **Customer Archived** - When a customer is archived +- **Customer Unarchived (Restored)** - When a customer is restored from archived state +- **Customer License Expiring** - Time-based warning of an upcoming license expiration +- **Pending Self-Service Signup** - When someone signs up via the self-service portal (if enabled) + +### Channel Events +- **Channel Created** - When a new channel is created for an application +- **Channel Archived** - When a channel is archived + +### Support Events +- **Support Bundle Uploaded** - When a support bundle is uploaded +- **Support Bundle Analyzed** - When a support bundle analysis is completed + +:::note +Instance related notifications will include the Instance Name if set, otherwise it will contain the Instance ID. +::: + +## Use Case Examples + +### Customer Success Manager: Key Customer Support Bundle +**Scenario:** As a Customer Success Manager, I want to be notified if one of my key customers uploads a support bundle. + +- **Event Type:** Support Bundle Uploaded +- **Configuration:** + - Filter - Customer: Select your key enterprise customer (e.g., "Acme Corp", "GlobalTech Inc", "Enterprise Solutions Ltd") + - Filter - Application: Select your production application +- **Delivery Method:** Email to your work email (or team email alias) + +### Sales Manager: Trial License Expiration +**Scenario:** As a Sales Manager, I want to be notified when a trial customer has an impending trial license expiration. + +- **Event Type:** Customer License Expiring +- **Configuration:** + - Filter - Application: Select your production application + - Filter - License Type: "Trial" +- **Delivery Method:** Email to your work email (or team email alias) + +### Product Manager: Release Promotion +**Scenario:** As a Product Manager, I want to be notified when a new release version is made available to customers on the Stable channel so that I can engage key customers in adoption follow-up conversations. + +- **Event Type:** Release Promoted +- **Configuration:** + - Filter - Application: Select your application + - Filter - Channel: Select "Stable" +- **Delivery Method:** Email to pm-team@company.com or webhook to #pm-team channel in Slack + +### Development Leader: Paid Customer Installations +**Scenario:** As a Development Leader, I want to be notified when a key customer pulls release assets to initiate a paid install. + +- **Event Type:** Release Asset Downloaded +- **Configuration:** + - Filter - Application: Select your application + - Filter - Channel: Select "Stable" + - Filter - License Type: "Paid" + - Filter - Asset Type: Any, or narrow further +- **Delivery Method:** Email to your work email (or team email alias) + +## Getting Started + +To start using Event Notifications: + +1. **Review available event types** - Identify which events are most relevant to your workflow +2. **Plan your filters** - Determine how you want to narrow event notifications (by customer, channel, license type, etc.) +3. **Choose delivery method** - Decide between email or webhook delivery (or both for different notifications) +4. **Create your first notification** - See [Create Event Notification Subscriptions (Beta)](event-notifications-create) +5. **Monitor and refine** - View notification history and adjust filters as needed + +## Prerequisites + +### RBAC Permissions + +To create and manage Event Notifications, you need appropriate RBAC permissions: + +- **Admin role** - Full access to all notification features including managing other users' subscriptions +- **Read Only role** - Can view all team notifications and their event history, but cannot create notifications +- **Other roles with write access** (Support Engineer, Sales, Custom) - Can create and modify their own notifications; broader team notifications are viewable but not modifiable (read-only) + +:::note +When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. +::: + +For teams using Custom RBAC policies, the following permissions are available: +- `team/notifications/**` - Full access to all notification features including managing other users' subscriptions +- `team/notifications/subscriptions/read` - View all team subscriptions +- `team/notifications/subscriptions/create` - Set up their own alerts +- `team/notifications/subscriptions/update` - Modify their own alerts +- `team/notifications/subscriptions/delete` - Remove their own alerts +- `team/notifications/types/list` - See available event types +- `team/notifications/events/read` - View notification history + +## Limitations + +Current limitations of Event Notifications (Beta): + +- Event Notifications does not yet cover all instance and custom metric event types from the legacy Instance Notifications feature, including Instance health state changed (aka Instance State Changed) +- Notification events generated are not included in the Instance Bulk Data Export API +- It is possible to create a notification for some resource types, such as customers and support bundles, but not be able to access the notification linked asset due to your allowed user permissions. This is most likely to impact teams with enterprise and custom RBAC policies. For example, someone with the Sales RBAC role can create a notification for a customer uploading a support bundle, but does not have permission to view the linked specific customer bundle due to their RBAC role permissions. +- The Release Assets Downloaded event may fire per chart/image if the customer pulls each separately as part of your installation instructions. As these assets can be shared across many release versions, the access event is recorded at the chart/image level and is not easily identifiable to a specific release version. If you find this alert too noisy, please reach out to us to further discuss your specific use case. + +:::note +Event Notifications can be used concurrently with the legacy Instance Notifications system while you evaluate and transition. +::: + +## Next Steps + +- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Learn how to create your first notification subscription +- [Manage Event Notification Subscriptions (Beta)](event-notifications-manage) - View, edit, and delete notification subscriptions +- [Event Notification Webhooks (Beta)](event-notifications-webhooks) - Configure webhooks for integration with tools like Slack + +## Related Topics + +- [Instance Notifications (Legacy)](instance-notifications-config) - Legacy per-instance notification system +- [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data +- [Enabling and Understanding Application Status](insights-app-status) - Understanding application status for instance events diff --git a/docs/vendor/instance-notifications-config.mdx b/docs/vendor/instance-notifications-config.mdx index 25057650c6..7f3bf26cdf 100644 --- a/docs/vendor/instance-notifications-config.mdx +++ b/docs/vendor/instance-notifications-config.mdx @@ -1,7 +1,13 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-about.mdx" -# Configure Instance Notifications (Beta) +# Configure Instance Notifications (Legacy) + +:::caution Legacy System +This notification system is being replaced by [Event Notifications (Beta)](event-notifications), which offers more event types, better filtering, and improved delivery options. While this legacy system continues to work, we recommend exploring Event Notifications for new notification configurations. + +For a comparison of features, see [Comparison: Legacy vs. Event Notifications](event-notifications#comparison-legacy-vs-event-notifications-beta). +::: @@ -56,4 +62,10 @@ Then, look for notifications in the assigned Slack channel. You also receive an :::note There is a 30-second buffer between event detection and notifications being sent. This buffer provides better roll-ups and reduces noise. -::: \ No newline at end of file +::: + +## See Also + +- [Event Notifications (Beta)](event-notifications) - New notification system with more event types and better filtering +- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Get started with Event Notifications +- [Comparison: Legacy vs. Event Notifications](event-notifications#comparison-legacy-vs-event-notifications-beta) - Feature comparison \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 7d9917e0de..983becece4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -184,6 +184,10 @@ const sidebars = { "vendor/customer-adoption", "vendor/customer-reporting", "vendor/instance-insights-details", + "vendor/event-notifications", + "vendor/event-notifications-create", + "vendor/event-notifications-manage", + "vendor/event-notifications-webhooks", "vendor/instance-notifications-config", "vendor/custom-metrics", "vendor/instance-data-export", From b823f2cdb1c156b7525892d2a8d27b45d9f98466 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Mon, 2 Feb 2026 11:37:41 -0700 Subject: [PATCH 02/23] Refine Event Notifications documentation based on feedback - Remove m-dash usage for more natural prose - Reorder Available Event Types: Instance, Customer, Support, Release, Channel - Add anchor links to Custom RBAC policy documentation - Simplify Create Event Notification section structure - Remove Bulk Management future feature mention - Remove detailed code examples from webhooks page (kept conceptual steps) - Remove Security Best Practices and Webhook Payload Examples sections - Reduce redundancy between Create and Manage pages - Replace "Legacy" terminology with "Classic" throughout - Update team-management-slack-config.mdx to mark as Classic system Co-Authored-By: Claude Sonnet 4.5 --- docs/vendor/event-notifications-create.mdx | 79 +------ docs/vendor/event-notifications-manage.mdx | 8 +- docs/vendor/event-notifications-webhooks.mdx | 218 ------------------ docs/vendor/event-notifications.mdx | 38 +-- docs/vendor/instance-notifications-config.mdx | 10 +- docs/vendor/team-management-slack-config.mdx | 19 +- 6 files changed, 46 insertions(+), 326 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 63929b16b7..623ae0db10 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -21,36 +21,19 @@ For webhook delivery: - A webhook endpoint URL that can receive POST requests - (Optional) A signing secret for HMAC signature verification -## Create a Notification from Scratch +## Create an Event Notification To create a new notification subscription: 1. Navigate to **Notifications** in the Vendor Portal -2. Click **"New Notification"** or **"Create Notification"** +2. Click **"Create Notification"** -3. **Select an event type** from the dropdown: - - Events are organized by category (Instance, Release, Customer, Channel, Support) - - Use the search box to quickly find event types - - Each event displays its description to help you choose +3. **Select an event type** from the dropdown -4. **Configure filters** for the event type: - - Available filters depend on the event type selected - - Most filters support dropdown selection from your existing resources - - Some filters support multiselect (e.g., License Type, Customer) - - Text filters allow pattern matching (e.g., Entitlement Filter) - - Leave filters empty to match all values - - **Common Filters:** - - **Application**: Filter by specific application - - **Channel**: Filter by release channel (Stable, Beta, Unstable, etc.) - - **Customer**: Filter by specific customer(s) - - **License Type**: Filter by license type (Trial, Paid, Community, Development) - - **Instance**: Filter by specific instance (for instance events) - - **Number of Versions Behind**: Threshold for version behind alerts - - **Days Until Expiry**: Threshold for license expiration warnings +4. **Configure filters** for the event type (optional) @@ -67,11 +50,7 @@ To create a new notification subscription: -6. (Optional) **Name your notification** for easy identification - - Use descriptive names like "Trial License Expiration Alerts" or "Acme Corp Support Bundles" - - Names help you quickly identify subscriptions in the list view - -7. Click **"Create Notification"** to activate +6. Click **"Create Notification"** to activate Your notification subscription is now active and will begin matching events based on your configured filters. @@ -152,52 +131,6 @@ Understanding how filters work will help you create effective notification subsc -## Testing Your Subscription - -After creating a notification subscription, verify that it works as expected: - -1. Trigger the event condition in a development or test environment - - For example, create a test customer or upload a support bundle -2. Check your email inbox or webhook endpoint for the notification -3. Review the notification history in the Vendor Portal: - - Navigate to **Notifications** > **History** - - Verify the event was captured and delivery was successful -4. If notifications aren't arriving: - - Verify email address is validated (check for verification email) - - Check that filters aren't too restrictive - - Review notification history for delivery errors - - For webhooks, see [Debugging Webhooks](event-notifications-webhooks#debugging) in _Event Notification Webhooks (Beta)_ - -## Troubleshooting - -### Notification Not Triggering - -If your notification subscription isn't triggering when expected: - -- **Check filters**: Ensure your filters aren't too restrictive and that the event meets all filter conditions -- **Verify subscription is active**: Inactive or disabled subscriptions won't trigger -- **Check email verification**: Unverified email addresses will block notifications from being sent -- **Review notification history**: Look for attempted deliveries and error messages - -### Email Not Received - -If you created a notification but aren't receiving emails: - -- **Check spam folder**: Notification emails may be filtered by email clients -- **Verify email address**: Ensure the email address is correct and has been verified -- **Check notification history**: Verify the notification was triggered and email delivery was attempted -- **Check your RBAC permissions**: Ensure you have `team/notifications/events/read` permission to view history - -### Webhook Not Receiving Notifications - -If your webhook endpoint isn't receiving notifications: - -- **Verify webhook URL**: Ensure the URL is correct and publicly accessible -- **Check webhook endpoint logs**: Verify your endpoint is responding with 2xx status codes -- **Test webhook manually**: Use a tool like `curl` to test your endpoint -- **Review notification history**: Check for delivery errors and retry attempts -- See [Event Notification Webhooks (Beta)](event-notifications-webhooks) for detailed webhook troubleshooting - ## Next Steps - [Manage Event Notification Subscriptions (Beta)](event-notifications-manage) - View, edit, and delete subscriptions @@ -207,4 +140,4 @@ If your webhook endpoint isn't receiving notifications: ## Related Topics - [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data -- [Custom RBAC Policies](team-management-rbac-configuring) - Configuring custom RBAC policies for notifications +- [Custom RBAC Policies](team-management-rbac-configuring#configure-a-custom-rbac-policy) - Configuring custom RBAC policies for notifications diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index 3517ff29c1..cfc1fc4353 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -225,12 +225,6 @@ To check if notifications are being delivered successfully: - Verify you have the necessary permissions to create and manage notifications - Contact your team admin if you need additional permissions -## Bulk Management (Future) - -:::note -Bulk management features such as bulk enable/disable and bulk delete are planned for a future release. -::: - ## Next Steps - [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Create new notification subscriptions @@ -239,5 +233,5 @@ Bulk management features such as bulk enable/disable and bulk delete are planned ## Related Topics -- [Custom RBAC Policies](team-management-rbac-configuring) - Configuring custom RBAC policies for notifications +- [Custom RBAC Policies](team-management-rbac-configuring#configure-a-custom-rbac-policy) - Configuring custom RBAC policies for notifications - [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 50b97e227c..79357a7fc9 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -156,96 +156,6 @@ if (!verifySignature(signature, expectedSignature)) { // Signature verified - process the webhook ``` -### Complete Verification Example (Node.js/Express) - -```javascript -const express = require('express'); -const crypto = require('crypto'); - -const app = express(); -const SIGNING_SECRET = process.env.WEBHOOK_SIGNING_SECRET; - -app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => { - // Extract signature from header - const signatureHeader = req.headers['x-replicated-signature']; - if (!signatureHeader) { - return res.status(401).send('Missing signature header'); - } - - const signature = signatureHeader.replace('sha256=', ''); - - // Compute expected signature - const hmac = crypto.createHmac('sha256', SIGNING_SECRET); - hmac.update(req.body); // Raw body buffer - const expectedSignature = hmac.digest('hex'); - - // Verify signature - try { - if (!crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expectedSignature, 'hex'))) { - return res.status(401).send('Invalid signature'); - } - } catch (err) { - return res.status(401).send('Invalid signature'); - } - - // Signature verified - parse and process webhook - const payload = JSON.parse(req.body.toString()); - console.log('Received event:', payload.event); - console.log('Event data:', payload.data); - - // Process the event... - - res.status(200).send('OK'); -}); - -app.listen(3000, () => console.log('Webhook server listening on port 3000')); -``` - -### Verification Example (Python/Flask) - -```python -from flask import Flask, request, jsonify -import hmac -import hashlib -import os - -app = Flask(__name__) -SIGNING_SECRET = os.environ.get('WEBHOOK_SIGNING_SECRET') - -@app.route('/webhook', methods=['POST']) -def webhook(): - # Extract signature from header - signature_header = request.headers.get('X-Replicated-Signature') - if not signature_header: - return 'Missing signature header', 401 - - signature = signature_header.replace('sha256=', '') - - # Compute expected signature - raw_body = request.get_data() - expected_signature = hmac.new( - SIGNING_SECRET.encode('utf-8'), - raw_body, - hashlib.sha256 - ).hexdigest() - - # Verify signature - if not hmac.compare_digest(signature, expected_signature): - return 'Invalid signature', 401 - - # Signature verified - parse and process webhook - payload = request.get_json() - print(f"Received event: {payload['event']}") - print(f"Event data: {payload['data']}") - - # Process the event... - - return 'OK', 200 - -if __name__ == '__main__': - app.run(port=3000) -``` - ## Integrating with Slack To send Event Notifications to a Slack channel using webhooks: @@ -352,133 +262,6 @@ To test webhooks during development: 3. **Trigger test events** and watch the ngrok dashboard or your application logs -## Security Best Practices - -### Always Verify Signatures - -- Always configure a signing secret when creating webhook subscriptions -- Always verify HMAC signatures in your endpoint before processing webhooks -- Reject requests with invalid or missing signatures - -### Use HTTPS Endpoints - -- Always use HTTPS webhook URLs in production -- Never use HTTP (unencrypted) endpoints for sensitive data - -### Implement Rate Limiting - -- Add rate limiting to your webhook endpoint to prevent abuse -- Consider implementing exponential backoff for retries in your application - -### Store Secrets Securely - -- Never hardcode signing secrets in your application code -- Use environment variables or a secrets management system -- Rotate signing secrets periodically - -### Process Webhooks Asynchronously - -- Return HTTP 200 immediately upon receiving webhooks -- Process webhook data in a background job or queue -- This prevents timeouts and improves reliability - -### Implement Idempotency - -- Use event timestamps and IDs to detect duplicate webhook deliveries -- Store processed event IDs to prevent duplicate processing -- Handle retries gracefully without side effects - -## Webhook Payload Examples by Event Type - -### Instance Events - -**Instance Created:** -```json -{ - "event": "instance.created", - "timestamp": "2026-01-30T10:15:32Z", - "text": "A new instance has been created...", - "data": { - "instance_id": "abc123", - "customer_id": "xyz789", - "app_name": "MyApp", - "channel_name": "Stable" - } -} -``` - -**Instance Upgraded:** -```json -{ - "event": "instance.upgraded", - "timestamp": "2026-01-30T10:20:45Z", - "text": "Instance upgraded to version 1.2.3...", - "data": { - "instance_id": "abc123", - "customer_id": "xyz789", - "version_label": "1.2.3", - "app_name": "MyApp" - } -} -``` - -### Release Events - -**Release Promoted:** -```json -{ - "event": "release.promoted", - "timestamp": "2026-01-30T11:00:00Z", - "text": "Release 1.2.3 promoted to Stable channel...", - "data": { - "release_sequence": 42, - "version_label": "1.2.3", - "channel_name": "Stable", - "app_name": "MyApp" - } -} -``` - -### Customer Events - -**Customer License Expiring:** -```json -{ - "event": "customer.license_expiring", - "timestamp": "2026-01-30T08:00:00Z", - "text": "Customer license expiring in 7 days...", - "data": { - "customer_id": "xyz789", - "customer_name": "Acme Corp", - "expires_at": "2026-02-06T00:00:00Z", - "days_until_expiry": 7, - "license_type": "trial" - } -} -``` - -### Support Events - -**Support Bundle Uploaded:** -```json -{ - "event": "supportbundle.uploaded", - "timestamp": "2026-01-30T14:30:00Z", - "text": "Support bundle uploaded by Acme Corp...", - "data": { - "bundle_id": "bundle123", - "customer_id": "xyz789", - "customer_name": "Acme Corp", - "instance_id": "abc123", - "app_name": "MyApp" - } -} -``` - -:::note -Payload structure varies by event type. The `data` object contains fields specific to each event. Use the webhook history view to inspect actual payloads for your events. -::: - ## Next Steps - [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Create webhook subscriptions @@ -488,4 +271,3 @@ Payload structure varies by event type. The `data` object contains fields specif ## Related Topics - [Slack Incoming Webhooks Documentation](https://api.slack.com/messaging/webhooks) - Setting up Slack webhooks -- [HMAC Verification Best Practices](https://en.wikipedia.org/wiki/HMAC) - Understanding HMAC signatures diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index 4eb7cc75fe..ce7034028e 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -14,19 +14,19 @@ Event types available are predefined, but these events can cover a broad range o Events are queued to SQS for reliable processing and notifications are matched against event filters in real-time. Email notifications are sent via the configured email service, and webhook notifications include HMAC signatures for verification. -## Key Differences from Legacy Instance Notifications +## Key Differences from Classic Instance Notifications -Event Notifications offers significant improvements over the legacy [Instance Notifications (Legacy)](instance-notifications-config) system: +Event Notifications offers significant improvements over the classic [Instance Notifications (Classic)](instance-notifications-config) system: -- **More event types available**: Including customer events, support bundle events, release events, channel events, and more—not just instance events +- **More event types available**: Covers customer events, support bundle events, release events, channel events, and more (not just instance events) - **More fine-grained alert customizability**: Improved filtering options let you target exactly what matters - **Flexible routing**: Route each notification to different individual or team alias email addresses or webhook payloads (for integrations such as Slack) - **Notification history**: View a complete history of event notifications sent - **Better access control**: Control over your individual notification configurations with visibility into broader team notifications configured -## Comparison: Legacy vs. Event Notifications (Beta) +## Comparison: Classic vs. Event Notifications (Beta) -| Feature | Legacy Instance Notifications | Event Notifications (Beta) | +| Feature | Classic Instance Notifications | Event Notifications (Beta) | |---------|------------------------------|---------------------------| | **Event Types** | 3 types (App Status, System Events, Custom Metrics) | 19+ types across 6 categories | | **Scope** | Per-instance subscriptions | Team-wide with flexible filtering | @@ -47,12 +47,6 @@ Event Notifications initially supports the following high-level event types. Eac - **Instance Version Behind** - When an instance falls behind by a specified number of versions - **Instance Inactive** - When an instance has not reported in for 24 hours (declared "Inactive") -### Release Events -- **Release Created** - When a new release is created -- **Release Promoted** - When a release is promoted to a channel -- **Release Demoted (Unpublished)** - When a release is demoted from a channel -- **Release Assets Downloaded** - When a release asset (such as a Helm chart or .tgz bundle) is pulled by a customer - ### Customer Events - **Customer Created** - When a new customer is created - **Customer Updated** - When a customer's details or license is updated @@ -61,14 +55,20 @@ Event Notifications initially supports the following high-level event types. Eac - **Customer License Expiring** - Time-based warning of an upcoming license expiration - **Pending Self-Service Signup** - When someone signs up via the self-service portal (if enabled) -### Channel Events -- **Channel Created** - When a new channel is created for an application -- **Channel Archived** - When a channel is archived - ### Support Events - **Support Bundle Uploaded** - When a support bundle is uploaded - **Support Bundle Analyzed** - When a support bundle analysis is completed +### Release Events +- **Release Created** - When a new release is created +- **Release Promoted** - When a release is promoted to a channel +- **Release Demoted (Unpublished)** - When a release is demoted from a channel +- **Release Assets Downloaded** - When a release asset (such as a Helm chart or .tgz bundle) is pulled by a customer + +### Channel Events +- **Channel Created** - When a new channel is created for an application +- **Channel Archived** - When a channel is archived + :::note Instance related notifications will include the Instance Name if set, otherwise it will contain the Instance ID. ::: @@ -137,7 +137,7 @@ To create and manage Event Notifications, you need appropriate RBAC permissions: When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. ::: -For teams using Custom RBAC policies, the following permissions are available: +For teams using [custom RBAC policies](team-management-rbac-configuring#configure-a-custom-rbac-policy), the following permissions are available: - `team/notifications/**` - Full access to all notification features including managing other users' subscriptions - `team/notifications/subscriptions/read` - View all team subscriptions - `team/notifications/subscriptions/create` - Set up their own alerts @@ -150,13 +150,13 @@ For teams using Custom RBAC policies, the following permissions are available: Current limitations of Event Notifications (Beta): -- Event Notifications does not yet cover all instance and custom metric event types from the legacy Instance Notifications feature, including Instance health state changed (aka Instance State Changed) +- Event Notifications does not yet cover all instance and custom metric event types from the classic Instance Notifications feature, including Instance health state changed (aka Instance State Changed) - Notification events generated are not included in the Instance Bulk Data Export API - It is possible to create a notification for some resource types, such as customers and support bundles, but not be able to access the notification linked asset due to your allowed user permissions. This is most likely to impact teams with enterprise and custom RBAC policies. For example, someone with the Sales RBAC role can create a notification for a customer uploading a support bundle, but does not have permission to view the linked specific customer bundle due to their RBAC role permissions. - The Release Assets Downloaded event may fire per chart/image if the customer pulls each separately as part of your installation instructions. As these assets can be shared across many release versions, the access event is recorded at the chart/image level and is not easily identifiable to a specific release version. If you find this alert too noisy, please reach out to us to further discuss your specific use case. :::note -Event Notifications can be used concurrently with the legacy Instance Notifications system while you evaluate and transition. +Event Notifications can be used concurrently with the classic Instance Notifications system while you evaluate and transition. ::: ## Next Steps @@ -167,6 +167,6 @@ Event Notifications can be used concurrently with the legacy Instance Notificati ## Related Topics -- [Instance Notifications (Legacy)](instance-notifications-config) - Legacy per-instance notification system +- [Instance Notifications (Classic)](instance-notifications-config) - Classic per-instance notification system - [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data - [Enabling and Understanding Application Status](insights-app-status) - Understanding application status for instance events diff --git a/docs/vendor/instance-notifications-config.mdx b/docs/vendor/instance-notifications-config.mdx index 7f3bf26cdf..5b715f6e3b 100644 --- a/docs/vendor/instance-notifications-config.mdx +++ b/docs/vendor/instance-notifications-config.mdx @@ -1,12 +1,12 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-about.mdx" -# Configure Instance Notifications (Legacy) +# Configure Instance Notifications (Classic) -:::caution Legacy System -This notification system is being replaced by [Event Notifications (Beta)](event-notifications), which offers more event types, better filtering, and improved delivery options. While this legacy system continues to work, we recommend exploring Event Notifications for new notification configurations. +:::caution Classic System +This notification system is being replaced by [Event Notifications (Beta)](event-notifications), which offers more event types, better filtering, and improved delivery options. While this classic system continues to work, we recommend exploring Event Notifications for new notification configurations. -For a comparison of features, see [Comparison: Legacy vs. Event Notifications](event-notifications#comparison-legacy-vs-event-notifications-beta). +For a comparison of features, see [Comparison: Classic vs. Event Notifications](event-notifications#comparison-classic-vs-event-notifications-beta). ::: @@ -68,4 +68,4 @@ There is a 30-second buffer between event detection and notifications being sent - [Event Notifications (Beta)](event-notifications) - New notification system with more event types and better filtering - [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Get started with Event Notifications -- [Comparison: Legacy vs. Event Notifications](event-notifications#comparison-legacy-vs-event-notifications-beta) - Feature comparison \ No newline at end of file +- [Comparison: Classic vs. Event Notifications](event-notifications#comparison-classic-vs-event-notifications-beta) - Feature comparison \ No newline at end of file diff --git a/docs/vendor/team-management-slack-config.mdx b/docs/vendor/team-management-slack-config.mdx index 3d7bd7939e..0d0ad3ea5e 100644 --- a/docs/vendor/team-management-slack-config.mdx +++ b/docs/vendor/team-management-slack-config.mdx @@ -1,7 +1,13 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-about.mdx" -# Configure a Slack Webhook (Beta) +# Configure a Slack Webhook (Classic) + +:::caution Classic System +This Slack webhook configuration is part of the classic Instance Notifications system, which is being replaced by [Event Notifications (Beta)](event-notifications). The new Event Notifications system supports direct webhook delivery to Slack (and other services) without requiring team-level Slack configuration. + +For new integrations, we recommend using [Event Notification Webhooks (Beta)](event-notifications-webhooks) instead. +::: As a vendor, anyone on your team can set up Slack notifications, which are sent to a shared Slack channel. Notifications give your team visibility into customer instance statuses and changes. @@ -11,7 +17,7 @@ While email notifications are specific to each user, Slack notifications setting ## Limitations -As a Beta feature, the following limitations apply: +The following limitations apply to classic Slack webhook configuration: - Only one Slack channel per team is supported. @@ -33,6 +39,11 @@ To configure the Slack webhook: 1. On the **Slack Notifications Setup** page, paste the Slack webhook URL. Click **Save**. -## Next Step +## Next Steps + +**For classic Instance Notifications:** +- [Configure Instance Notifications (Classic)](instance-notifications-config) - Configure Slack notifications for customer instances -[Configure Slack notifications for customer instances](instance-notifications-config). +**For new Event Notifications:** +- [Event Notification Webhooks (Beta)](event-notifications-webhooks) - Send notifications directly to Slack using webhooks (no team-level configuration required) +- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Set up notification subscriptions with the new system From 9a4d3091e4a5f3436c5c3c349fa08a8d0f786720 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Mon, 2 Feb 2026 11:44:59 -0700 Subject: [PATCH 03/23] Remove Beta note from classic notifications partial Remove outdated Beta note from classic Instance Notifications pages. The classic system is stable and no longer in Beta. Co-Authored-By: Claude Sonnet 4.5 --- docs/partials/instance-insights/_notifications-about.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/partials/instance-insights/_notifications-about.mdx b/docs/partials/instance-insights/_notifications-about.mdx index 04ce63a1e4..b4ca5c54a5 100644 --- a/docs/partials/instance-insights/_notifications-about.mdx +++ b/docs/partials/instance-insights/_notifications-about.mdx @@ -1,7 +1,3 @@ -:::note -Configuring notifications for customer instance changes is in public Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. -::: - Notifications can help catch problems before they happen and let you proactively contact customers to prevent support cases. For example, you can be notified of a degraded status and you can contact your customer about fixing it before the instance goes down. This approach can make issues quicker and easier to solve, and improve the customer experience with less down time. For more information about how application status is determined, see [Resource Statuses](insights-app-status#resource-statuses) in _Enabling and Understanding Application Status_. For more information about events that might trigger notifications, see [How the Vendor Portal Generates Events and Insights](instance-insights-event-data#about-events) in _About Instance and Event Data_. From defe6df3736ee4ea05cfd326652487fc1539a5df Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Mon, 2 Feb 2026 12:53:16 -0700 Subject: [PATCH 04/23] Apply additional refinements to Event Notifications docs - Update sidebar: reorder Insights and Telemetry navigation - Simplify leading sentence on overview page - Update comparison chart delivery values - Remove Status row from comparison chart - Make email non-clickable in Product Manager example - Change "key customer" to "paid customer" in Dev Leader example - Add missing links in limitations section - Remove Instance Notifications (Classic) from Related Topics - Remove Notification List Filtering and Sorting section - Remove Related Topics section from webhooks page Co-Authored-By: Claude Sonnet 4.5 --- docs/vendor/event-notifications-manage.mdx | 17 ----------------- docs/vendor/event-notifications-webhooks.mdx | 4 ---- docs/vendor/event-notifications.mdx | 14 ++++++-------- sidebars.js | 2 +- 4 files changed, 7 insertions(+), 30 deletions(-) diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index cfc1fc4353..7084fd84e2 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -175,23 +175,6 @@ Event Notifications uses team-scoped RBAC permissions to control access. Your ab When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. ::: -## Notification List Filtering and Sorting - -The Notifications list page supports filtering and sorting to help you find specific subscriptions: - -**Available filters:** -- Active vs. Inactive subscriptions -- Event type -- Delivery method (Email or Webhook) -- Created by (for Team Notifications view) - -**Sorting options:** -- Name (A-Z or Z-A) -- Created date (newest or oldest first) -- Last triggered (most recent or least recent) - -Use these tools to quickly locate and manage your notification subscriptions. - ## Troubleshooting Notification Delivery ### Viewing Delivery Status diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 79357a7fc9..ba86d792ae 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -267,7 +267,3 @@ To test webhooks during development: - [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Create webhook subscriptions - [Manage Event Notification Subscriptions (Beta)](event-notifications-manage) - View webhook delivery history - [Event Notifications (Beta)](event-notifications) - Overview and available event types - -## Related Topics - -- [Slack Incoming Webhooks Documentation](https://api.slack.com/messaging/webhooks) - Setting up Slack webhooks diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index ce7034028e..b6f91282e5 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -4,7 +4,7 @@ Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. ::: -The ability to set up notifications for key events of interest within the Replicated Vendor Portal can help you proactively manage and prevent issues across your customer instances, releases, support bundles, and more. +The ability to set up notifications for key events of interest within Vendor Portal can help you proactively manage and prevent issues. ## Overview @@ -30,12 +30,11 @@ Event Notifications offers significant improvements over the classic [Instance N |---------|------------------------------|---------------------------| | **Event Types** | 3 types (App Status, System Events, Custom Metrics) | 19+ types across 6 categories | | **Scope** | Per-instance subscriptions | Team-wide with flexible filtering | -| **Delivery** | Slack (team webhook) + Email (user) | Email + Generic webhooks | +| **Delivery** | Slack (1 team webhook) + Email (1 user) | Per notification email or webhook | | **Filtering** | Instance-level only | Multi-field filters (app, customer, channel, etc.) | | **Permissions** | User-scoped | Team-scoped RBAC | | **Webhook Security** | Basic | HMAC-SHA256 signing | | **Notification History** | Minimal | Full delivery attempt tracking with event details | -| **Status** | Maintenance mode | Active development | ## Available Event Types @@ -100,10 +99,10 @@ Instance related notifications will include the Instance Name if set, otherwise - **Configuration:** - Filter - Application: Select your application - Filter - Channel: Select "Stable" -- **Delivery Method:** Email to pm-team@company.com or webhook to #pm-team channel in Slack +- **Delivery Method:** Email to `pm-team@company.com` or webhook to #pm-team channel in Slack ### Development Leader: Paid Customer Installations -**Scenario:** As a Development Leader, I want to be notified when a key customer pulls release assets to initiate a paid install. +**Scenario:** As a Development Leader, I want to be notified when a paid customer pulls release assets to initiate a paid install. - **Event Type:** Release Asset Downloaded - **Configuration:** @@ -151,8 +150,8 @@ For teams using [custom RBAC policies](team-management-rbac-configuring#configur Current limitations of Event Notifications (Beta): - Event Notifications does not yet cover all instance and custom metric event types from the classic Instance Notifications feature, including Instance health state changed (aka Instance State Changed) -- Notification events generated are not included in the Instance Bulk Data Export API -- It is possible to create a notification for some resource types, such as customers and support bundles, but not be able to access the notification linked asset due to your allowed user permissions. This is most likely to impact teams with enterprise and custom RBAC policies. For example, someone with the Sales RBAC role can create a notification for a customer uploading a support bundle, but does not have permission to view the linked specific customer bundle due to their RBAC role permissions. +- Notification events generated are not included in the [Instance Bulk Data Export API](instance-data-export) +- It is possible to create a notification for some resource types, such as customers and support bundles, but not be able to access the notification linked asset due to your allowed user permissions. This is most likely to impact teams with [enterprise and custom RBAC policies](team-management-rbac-configuring). For example, someone with the [Sales RBAC role](team-management-rbac-configuring) can create a notification for a customer uploading a support bundle, but does not have permission to view the linked specific customer bundle due to their RBAC role permissions. - The Release Assets Downloaded event may fire per chart/image if the customer pulls each separately as part of your installation instructions. As these assets can be shared across many release versions, the access event is recorded at the chart/image level and is not easily identifiable to a specific release version. If you find this alert too noisy, please reach out to us to further discuss your specific use case. :::note @@ -167,6 +166,5 @@ Event Notifications can be used concurrently with the classic Instance Notificat ## Related Topics -- [Instance Notifications (Classic)](instance-notifications-config) - Classic per-instance notification system - [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data - [Enabling and Understanding Application Status](insights-app-status) - Understanding application status for instance events diff --git a/sidebars.js b/sidebars.js index 983becece4..9e1ef3ab75 100644 --- a/sidebars.js +++ b/sidebars.js @@ -180,6 +180,7 @@ const sidebars = { items: [ "vendor/instance-insights-event-data", "vendor/insights-app-status", + "vendor/custom-metrics", "vendor/telemetry-air-gap", "vendor/customer-adoption", "vendor/customer-reporting", @@ -189,7 +190,6 @@ const sidebars = { "vendor/event-notifications-manage", "vendor/event-notifications-webhooks", "vendor/instance-notifications-config", - "vendor/custom-metrics", "vendor/instance-data-export", ], }, From 850613b498feae6862bb1f7f1f1ddf8808219a88 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Mon, 2 Feb 2026 13:00:40 -0700 Subject: [PATCH 05/23] Update webhooks page title to include 'Configure' Changed title from "Event Notification Webhooks (Beta)" to "Configure Event Notification Webhooks (Beta)" for clarity. Co-Authored-By: Claude Sonnet 4.5 --- docs/vendor/event-notifications-webhooks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index ba86d792ae..9966e2b6ad 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -1,4 +1,4 @@ -# Event Notification Webhooks (Beta) +# Configure Event Notification Webhooks (Beta) :::note Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. From 7c2067e4c45ac5b9a024744690b9b82c60c881aa Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Mon, 2 Feb 2026 17:02:11 -0700 Subject: [PATCH 06/23] Refine Event Notifications docs based on review feedback Structural changes: - Reorganize sidebar with Event Notifications (Beta) subsection - Move permissions content from manage page to overview page - Remove "Next Steps" and "Related Topics" sections (sidebar handles navigation) Terminology and style: - Update main page title to "About Event Notifications (Beta)" - Simplify terminology: use "notifications" instead of "notification subscriptions" - Use "Disabled" instead of "Paused" for clarity - Update headings to infinitive verb form - Remove bold from procedural text (reserved for UI elements only) Content improvements: - Combine "Key Differences" section with comparison table - Absorb "Getting Started" into Overview section - Expand Prerequisites with detailed RBAC permissions - Add link from filter configuration to Filter Logic section RBAC documentation: - Add event notification permissions to team-management-rbac-resource-names.md Co-Authored-By: Claude Sonnet 4.5 --- docs/vendor/event-notifications-create.mdx | 47 ++++++++------ docs/vendor/event-notifications-manage.mdx | 57 ++++------------- docs/vendor/event-notifications.mdx | 64 ++++++------------- .../team-management-rbac-resource-names.md | 28 ++++++++ sidebars.js | 14 ++-- 5 files changed, 95 insertions(+), 115 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 623ae0db10..14fb37e101 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -12,14 +12,30 @@ You can create notification subscriptions from scratch to receive alerts when sp ## Prerequisites -Before creating event notification subscriptions, ensure you have: +### RBAC Permissions -- **RBAC Permissions**: Appropriate permissions to create notifications. See [RBAC Permissions](event-notifications#prerequisites) in _Event Notifications (Beta)_. -- **Email or Webhook URL**: A destination for your notifications (your email address or a webhook URL for integrations like Slack). +To create and manage Event Notifications, you need appropriate RBAC permissions: -For webhook delivery: -- A webhook endpoint URL that can receive POST requests -- (Optional) A signing secret for HMAC signature verification +- **Admin role** - Full access to all notification features including managing other users' subscriptions +- **Read Only role** - Can view all team notifications and their event history, but cannot create notifications +- **Other roles with write access** (Support Engineer, Sales, Custom) - Can create and modify their own notifications; broader team notifications are viewable but not modifiable (read-only) + +:::note +When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. +::: + +For teams using [custom RBAC policies](team-management-rbac-configuring#configure-a-custom-rbac-policy), the following permissions are available: +- `team/notifications/**` - Full access to all notification features including managing other users' subscriptions +- `team/notifications/subscriptions/read` - View all team subscriptions +- `team/notifications/subscriptions/create` - Set up their own alerts +- `team/notifications/subscriptions/update` - Modify their own alerts +- `team/notifications/subscriptions/delete` - Remove their own alerts +- `team/notifications/types/list` - See available event types +- `team/notifications/events/read` - View notification history + +### Webhook Configuration + +For webhook delivery, see [Configure Event Notification Webhooks (Beta)](event-notifications-webhooks) to set up your webhook endpoint. ## Create an Event Notification @@ -29,15 +45,15 @@ To create a new notification subscription: 2. Click **"Create Notification"** -3. **Select an event type** from the dropdown +3. Select an event type from the dropdown -4. **Configure filters** for the event type (optional) +4. Configure filters for the event type (optional). For more information about how filters work, see [Filter Logic](#filter-logic). -5. **Choose your notification delivery method**: +5. Choose your notification delivery method: ### Email Delivery - Enter an email address @@ -54,7 +70,7 @@ To create a new notification subscription: Your notification subscription is now active and will begin matching events based on your configured filters. -## Email Verification {#email-verification} +## Verify Your Email Address {#email-verification} When sending to an email address other than the one associated with your Vendor Portal user account, you must first validate that email before notifications can be sent. @@ -130,14 +146,3 @@ Understanding how filters work will help you create effective notification subsc - **Result**: Notification triggers when either trial OR paid customer licenses for MyApp are expiring - -## Next Steps - -- [Manage Event Notification Subscriptions (Beta)](event-notifications-manage) - View, edit, and delete subscriptions -- [Event Notification Webhooks (Beta)](event-notifications-webhooks) - Configure webhooks for integrations like Slack -- [Event Notifications (Beta)](event-notifications) - Overview and available event types - -## Related Topics - -- [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data -- [Custom RBAC Policies](team-management-rbac-configuring#configure-a-custom-rbac-policy) - Configuring custom RBAC policies for notifications diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index 7084fd84e2..dc884dab90 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -4,11 +4,11 @@ Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. ::: -This topic describes how to view, edit, disable, and delete event notification subscriptions in the Replicated Vendor Portal. +This topic describes how to view, edit, disable, and delete event notifications in the Replicated Vendor Portal. ## Overview -The Notifications page in the Vendor Portal provides visibility into both personal and team notification subscriptions, as well as a complete history of notification events. You can manage your own subscriptions and, if you have the appropriate permissions, view and manage team subscriptions. +The Notifications page in the Vendor Portal provides visibility into both personal and team notifications, as well as a complete history of notification events. You can manage your own subscriptions and, if you have the appropriate permissions, view and manage team subscriptions. ## Viewing Notification Subscriptions @@ -16,7 +16,7 @@ The Notifications list page provides three main views: ### My Notifications -Shows only notification subscriptions you created, giving you quick access to manage your personal monitoring setup. +Shows only notifications you created, giving you quick access to manage your personal monitoring setup. To view your notifications: @@ -28,7 +28,7 @@ To view your notifications: ### Team Notifications -Shows all notification subscriptions created by anyone on your team. This view is useful for understanding what monitoring is in place across the organization. +Shows all notifications created by anyone on your team. This view is useful for understanding what monitoring is in place across the organization. To view team notifications: @@ -53,7 +53,7 @@ To view notification history: 3. Use the filters to narrow results: - Filter by time period - Filter to "My Notifications Only" - - Filter to a specific notification subscription + - Filter to a specific notification @@ -78,7 +78,7 @@ This information is helpful for troubleshooting notification delivery issues and ## Editing an Existing Notification -To modify a notification subscription: +To modify a notification: 1. Navigate to **Notifications** in the Vendor Portal @@ -105,14 +105,14 @@ To modify a notification subscription: - Changes apply immediately to future events - You can only edit notifications you created, unless you're a team admin with permissions to manage all team notifications -## Disabling a Notification (Pause) +## Disable a Notification To temporarily stop a notification without deleting it: 1. Navigate to **Notifications** in the Vendor Portal 2. Find the notification in the list 3. Click the **Edit** button -4. Toggle the notification to **Disabled** or **Paused** state +4. Toggle the notification to **Disabled** state 5. Save your changes When a notification is disabled: @@ -123,7 +123,7 @@ When a notification is disabled: ## Deleting an Existing Notification -To permanently remove a notification subscription: +To permanently remove a notification: 1. Navigate to **Notifications** in the Vendor Portal @@ -149,33 +149,9 @@ Each notification maintains a history of when it triggered and what events match 2. Find the notification in the list (either **My Notifications** or **Team Notifications**) 3. Click the **"View History"** button for that notification -This filtered view shows only events that matched this specific notification subscription, making it easier to understand the notification's behavior and troubleshoot any issues. +This filtered view shows only events that matched this specific notification, making it easier to understand the notification's behavior and troubleshoot any issues. -## Understanding Notification Permissions - -Event Notifications uses team-scoped RBAC permissions to control access. Your ability to view and manage notifications depends on your role: - -### Admin Role -- Can manage any team-created notifications in addition to their own -- Can modify, delete, and turn off/on any notification -- Full access to all notification features - -### Read Only Role -- Cannot create notifications -- Can view all team notifications and their event history -- No modification permissions - -### Other Non-Admin Roles with Write Access -(Examples: Support Engineer, Sales, Custom roles) -- Can create and modify their own notifications -- Broader team notifications are viewable but not modifiable (read-only) -- Cannot edit or delete subscriptions created by other team members - -:::note -When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. -::: - -## Troubleshooting Notification Delivery +## Troubleshoot Notification Delivery ### Viewing Delivery Status @@ -207,14 +183,3 @@ To check if notifications are being delivered successfully: **RBAC permissions:** - Verify you have the necessary permissions to create and manage notifications - Contact your team admin if you need additional permissions - -## Next Steps - -- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Create new notification subscriptions -- [Event Notification Webhooks (Beta)](event-notifications-webhooks) - Configure webhooks for integrations like Slack -- [Event Notifications (Beta)](event-notifications) - Overview and available event types - -## Related Topics - -- [Custom RBAC Policies](team-management-rbac-configuring#configure-a-custom-rbac-policy) - Configuring custom RBAC policies for notifications -- [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index b6f91282e5..f091856e8b 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -1,4 +1,4 @@ -# Event Notifications (Beta) +# About Event Notifications (Beta) :::note Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. @@ -14,17 +14,11 @@ Event types available are predefined, but these events can cover a broad range o Events are queued to SQS for reliable processing and notifications are matched against event filters in real-time. Email notifications are sent via the configured email service, and webhook notifications include HMAC signatures for verification. -## Key Differences from Classic Instance Notifications +To get started, review the available event types below, plan your filters based on your workflow needs (by customer, channel, license type, etc.), and choose your delivery method (email or webhook). Then create your first notification using the steps in [Create Event Notification Subscriptions (Beta)](event-notifications-create) and monitor the notification history to refine your filters as needed. -Event Notifications offers significant improvements over the classic [Instance Notifications (Classic)](instance-notifications-config) system: +## Comparison: Classic Instance Notifications vs. Event Notifications (Beta) -- **More event types available**: Covers customer events, support bundle events, release events, channel events, and more (not just instance events) -- **More fine-grained alert customizability**: Improved filtering options let you target exactly what matters -- **Flexible routing**: Route each notification to different individual or team alias email addresses or webhook payloads (for integrations such as Slack) -- **Notification history**: View a complete history of event notifications sent -- **Better access control**: Control over your individual notification configurations with visibility into broader team notifications configured - -## Comparison: Classic vs. Event Notifications (Beta) +Event Notifications offers significant improvements over the classic [Instance Notifications (Classic)](instance-notifications-config) system, including more event types, fine-grained filtering, flexible routing to individual or team email addresses or webhooks, notification history tracking, and better access control. | Feature | Classic Instance Notifications | Event Notifications (Beta) | |---------|------------------------------|---------------------------| @@ -112,38 +106,31 @@ Instance related notifications will include the Instance Name if set, otherwise - Filter - Asset Type: Any, or narrow further - **Delivery Method:** Email to your work email (or team email alias) -## Getting Started - -To start using Event Notifications: +## Permissions -1. **Review available event types** - Identify which events are most relevant to your workflow -2. **Plan your filters** - Determine how you want to narrow event notifications (by customer, channel, license type, etc.) -3. **Choose delivery method** - Decide between email or webhook delivery (or both for different notifications) -4. **Create your first notification** - See [Create Event Notification Subscriptions (Beta)](event-notifications-create) -5. **Monitor and refine** - View notification history and adjust filters as needed +Event Notifications uses team-scoped RBAC permissions to control access. Your ability to view and manage notifications depends on your role: -## Prerequisites +### Admin Role +- Can manage any team-created notifications in addition to their own +- Can modify, delete, and turn off/on any notification +- Full access to all notification features -### RBAC Permissions +### Read Only Role +- Cannot create notifications +- Can view all team notifications and their event history +- No modification permissions -To create and manage Event Notifications, you need appropriate RBAC permissions: - -- **Admin role** - Full access to all notification features including managing other users' subscriptions -- **Read Only role** - Can view all team notifications and their event history, but cannot create notifications -- **Other roles with write access** (Support Engineer, Sales, Custom) - Can create and modify their own notifications; broader team notifications are viewable but not modifiable (read-only) +### Other Non-Admin Roles with Write Access +(Examples: Support Engineer, Sales, Custom roles) +- Can create and modify their own notifications +- Broader team notifications are viewable but not modifiable (read-only) +- Cannot edit or delete notifications created by other team members :::note When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. ::: -For teams using [custom RBAC policies](team-management-rbac-configuring#configure-a-custom-rbac-policy), the following permissions are available: -- `team/notifications/**` - Full access to all notification features including managing other users' subscriptions -- `team/notifications/subscriptions/read` - View all team subscriptions -- `team/notifications/subscriptions/create` - Set up their own alerts -- `team/notifications/subscriptions/update` - Modify their own alerts -- `team/notifications/subscriptions/delete` - Remove their own alerts -- `team/notifications/types/list` - See available event types -- `team/notifications/events/read` - View notification history +For detailed information about custom RBAC policies and notification permissions, see [Create Event Notification Subscriptions (Beta)](event-notifications-create). ## Limitations @@ -157,14 +144,3 @@ Current limitations of Event Notifications (Beta): :::note Event Notifications can be used concurrently with the classic Instance Notifications system while you evaluate and transition. ::: - -## Next Steps - -- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Learn how to create your first notification subscription -- [Manage Event Notification Subscriptions (Beta)](event-notifications-manage) - View, edit, and delete notification subscriptions -- [Event Notification Webhooks (Beta)](event-notifications-webhooks) - Configure webhooks for integration with tools like Slack - -## Related Topics - -- [About Instance and Event Data](instance-insights-event-data) - How the Vendor Portal collects instance data -- [Enabling and Understanding Application Status](insights-app-status) - Understanding application status for instance events diff --git a/docs/vendor/team-management-rbac-resource-names.md b/docs/vendor/team-management-rbac-resource-names.md index d161f30237..0242d5dcc0 100644 --- a/docs/vendor/team-management-rbac-resource-names.md +++ b/docs/vendor/team-management-rbac-resource-names.md @@ -488,6 +488,34 @@ Grants the holder permission to view the team's Slack webhook for instance notif Grants the holder permission to edit the team's Slack webhook for instance notifications. +### team/notifications/\*\* + +Grants the holder full access to all notification features, including managing other users' event notification subscriptions. For more information, see [About Event Notifications (Beta)](event-notifications). + +### team/notifications/subscriptions/read + +Grants the holder permission to view all team event notification subscriptions. + +### team/notifications/subscriptions/create + +Grants the holder permission to create their own event notification subscriptions. + +### team/notifications/subscriptions/update + +Grants the holder permission to modify their own event notification subscriptions. + +### team/notifications/subscriptions/delete + +Grants the holder permission to delete their own event notification subscriptions. + +### team/notifications/types/list + +Grants the holder permission to see available event notification types. + +### team/notifications/events/read + +Grants the holder permission to view event notification history. + ### team/policy/read Grants the holder permission to view RBAC policies for the team. diff --git a/sidebars.js b/sidebars.js index 9e1ef3ab75..8374fc7cb1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -185,10 +185,16 @@ const sidebars = { "vendor/customer-adoption", "vendor/customer-reporting", "vendor/instance-insights-details", - "vendor/event-notifications", - "vendor/event-notifications-create", - "vendor/event-notifications-manage", - "vendor/event-notifications-webhooks", + { + type: "category", + label: "Event Notifications (Beta)", + items: [ + "vendor/event-notifications", + "vendor/event-notifications-create", + "vendor/event-notifications-manage", + "vendor/event-notifications-webhooks", + ], + }, "vendor/instance-notifications-config", "vendor/instance-data-export", ], From 6418b861d669836b2a3d40fb51673547e666e496 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Fri, 13 Feb 2026 08:56:46 -0700 Subject: [PATCH 07/23] Remove duplicate RBAC notification entries already merged in #3827 Removes individual notification permission entries (subscriptions/read, create, update, delete, types/list, events/read) that were already published via PR #3827. Retains the team/notifications/** wildcard entry which was not covered by that PR. Co-Authored-By: Claude Opus 4.6 --- .../team-management-rbac-resource-names.md | 24 ------------------- 1 file changed, 24 deletions(-) diff --git a/docs/vendor/team-management-rbac-resource-names.md b/docs/vendor/team-management-rbac-resource-names.md index 0242d5dcc0..e4bbc538d0 100644 --- a/docs/vendor/team-management-rbac-resource-names.md +++ b/docs/vendor/team-management-rbac-resource-names.md @@ -492,30 +492,6 @@ Grants the holder permission to edit the team's Slack webhook for instance notif Grants the holder full access to all notification features, including managing other users' event notification subscriptions. For more information, see [About Event Notifications (Beta)](event-notifications). -### team/notifications/subscriptions/read - -Grants the holder permission to view all team event notification subscriptions. - -### team/notifications/subscriptions/create - -Grants the holder permission to create their own event notification subscriptions. - -### team/notifications/subscriptions/update - -Grants the holder permission to modify their own event notification subscriptions. - -### team/notifications/subscriptions/delete - -Grants the holder permission to delete their own event notification subscriptions. - -### team/notifications/types/list - -Grants the holder permission to see available event notification types. - -### team/notifications/events/read - -Grants the holder permission to view event notification history. - ### team/policy/read Grants the holder permission to view RBAC policies for the team. From d3aa8dabec14982232688588e7b68c8773c4d742 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Fri, 13 Feb 2026 09:01:46 -0700 Subject: [PATCH 08/23] Clarify Slack webhook RBAC permissions as classic notifications Updates the team/notifications/slack-webhook/read and team/notifications/slack-webhook/update descriptions to indicate they apply to the classic instance notifications system, with cross-references to the classic notifications page. Co-Authored-By: Claude Opus 4.6 --- docs/vendor/team-management-rbac-resource-names.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/vendor/team-management-rbac-resource-names.md b/docs/vendor/team-management-rbac-resource-names.md index e4bbc538d0..b46c701962 100644 --- a/docs/vendor/team-management-rbac-resource-names.md +++ b/docs/vendor/team-management-rbac-resource-names.md @@ -482,11 +482,11 @@ Grants the holder permission to delete other team members. ### team/notifications/slack-webhook/read -Grants the holder permission to view the team's Slack webhook for instance notifications. +Grants the holder permission to view the team's Slack webhook for classic instance notifications. For more information, see [Configure Instance Notifications (Classic)](instance-notifications-config). ### team/notifications/slack-webhook/update -Grants the holder permission to edit the team's Slack webhook for instance notifications. +Grants the holder permission to edit the team's Slack webhook for classic instance notifications. For more information, see [Configure Instance Notifications (Classic)](instance-notifications-config). ### team/notifications/\*\* From ba388591c58f97d98b69721b661047128747a5e9 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Fri, 13 Feb 2026 09:41:47 -0700 Subject: [PATCH 09/23] Document custom subscription names, search, card metadata, and filter UX Reflects recent feature work: custom subscription naming (PR #8951), enhanced card metadata display (PR #8942), preserved history after deletion (PR #8937), and auto-opening filter modal (PR #8952). Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications-create.mdx | 14 ++++++++++---- docs/vendor/event-notifications-manage.mdx | 10 +++++++--- docs/vendor/event-notifications-webhooks.mdx | 8 +++++++- 3 files changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 14fb37e101..0465eded63 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -45,15 +45,21 @@ To create a new notification subscription: 2. Click **"Create Notification"** -3. Select an event type from the dropdown +3. (Optional) Enter a custom name for the subscription. Custom names help you identify subscriptions when you have multiple subscriptions for the same event type. The name is also included in email subjects and webhook payloads. + + :::note + Subscription names can contain up to 255 ASCII characters (letters, numbers, and basic punctuation). + ::: + +4. Select an event type from the dropdown -4. Configure filters for the event type (optional). For more information about how filters work, see [Filter Logic](#filter-logic). +5. Configure filters for the event type. If filters are available for the selected event type, the filter configuration modal opens automatically. For more information about how filters work, see [Filter Logic](#filter-logic). -5. Choose your notification delivery method: +6. Choose your notification delivery method: ### Email Delivery - Enter an email address @@ -66,7 +72,7 @@ To create a new notification subscription: -6. Click **"Create Notification"** to activate +7. Click **"Create Notification"** to activate Your notification subscription is now active and will begin matching events based on your configured filters. diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index dc884dab90..8629d21601 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -23,9 +23,12 @@ To view your notifications: 1. Navigate to **Notifications** in the Vendor Portal 2. Select the **My Notifications** tab 3. View the list of your active and inactive subscriptions +4. (Optional) Use the search bar to filter subscriptions by name or event type +Each subscription card displays the delivery channel (email or webhook), the delivery address, the date created, and who created it. If a custom name is set, it appears as the card title. + ### Team Notifications Shows all notifications created by anyone on your team. This view is useful for understanding what monitoring is in place across the organization. @@ -35,6 +38,7 @@ To view team notifications: 1. Navigate to **Notifications** in the Vendor Portal 2. Select the **Team Notifications** tab 3. View all subscriptions created by team members +4. (Optional) Use the search bar to filter subscriptions by name or event type **Permissions:** - **Team admins** can manage (edit/delete) any team member's notifications @@ -44,7 +48,7 @@ To view team notifications: ### History -Shows all triggered notification events for the selected time period. You can filter the history to show only your notifications or filter by a specific configured notification. +Shows all triggered notification events for the selected time period. You can filter the history to show only your notifications or filter by a specific notification, including deleted subscriptions. To view notification history: @@ -53,7 +57,7 @@ To view notification history: 3. Use the filters to narrow results: - Filter by time period - Filter to "My Notifications Only" - - Filter to a specific notification + - Filter to a specific notification (active or deleted) @@ -91,9 +95,9 @@ To modify a notification: 4. The notification form will open with all current settings populated 5. Make your desired changes: + - Add or update a custom subscription name to help identify the subscription - Modify filters to broaden or narrow the scope - Change the delivery method or destination - - Update the notification name - Pause/unpause the notification 6. Click **"Save Changes"** to update diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 9966e2b6ad..2984bab694 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -62,11 +62,16 @@ Event Notifications webhooks deliver a JSON payload with the following structure "customer_id": "38ljzNKNZZSIp3bUQYSPzJUUBpd", "channel_name": "Stable", "license_type": "trial", - "customer_name": "Testy McTestface" + "customer_name": "Testy McTestface", + "subscription_name": "Trial Customer Alerts" } } ``` +:::note +The `subscription_name` field is included in the `data` object only when a custom name is set on the subscription. For email notifications, the custom name is prepended to the email subject line. +::: + ### Payload Fields | Field | Type | Description | @@ -82,6 +87,7 @@ The `data` object contains fields specific to each event type. Common fields inc - `app_name` - Application name - `app_slug` - Application slug (URL-safe identifier) - `event_type` - Event type identifier +- `subscription_name` - Custom subscription name, if set - Additional fields specific to the event type (customer_id, instance_id, channel_id, etc.) ## Webhook Signing (HMAC-SHA256) From cc8efdb831102476bb7e4f52315a89535f5c53e2 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Tue, 17 Feb 2026 15:52:12 -0700 Subject: [PATCH 10/23] Updated for recent UI improvements and addition of license field filtering ability Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications-create.mdx | 29 +++++++++++++ docs/vendor/event-notifications-manage.mdx | 47 ++++++++-------------- docs/vendor/event-notifications.mdx | 5 ++- 3 files changed, 48 insertions(+), 33 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 0465eded63..70ef069919 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -132,6 +132,29 @@ Understanding how filters work will help you create effective notification subsc - **One or more filters specified**: The event must match **all specified filters** to trigger the notification (AND logic) - **Multi-select filters**: If a filter contains multiple selected values, the event must match **any** of the selected values within that filter to trigger the notification (OR logic within the filter) +### License Field Condition Filters + +For customer-related and instance-related events, you can filter notifications based on custom license field (entitlement) values. This allows you to create targeted notifications based on your customers' entitlement data. + +License field conditions use a three-part structure: field, operator, and value. The available operators depend on the field type: + +| Field Type | Available Operators | +|------------|-------------------| +| Integer | equals, does not equal, greater than, less than, greater than or equal, less than or equal | +| String / Text | equals, does not equal, contains, does not contain | +| Boolean | is true, is false | + +When multiple license field conditions are specified, all conditions must match for the notification to trigger (AND logic). + +License field conditions are available for the following event types: +- All Customer events (Customer Created, Customer Updated, Customer Archived, Customer Unarchived, Customer License Expiring) +- All Instance events (Instance Created, Instance Upgraded, Instance Version Behind, Instance Inactive) +- Support Bundle events (Support Bundle Uploaded, Support Bundle Analyzed) + +:::note +License field conditions are not available for Pending Self-Service Signup, Release, or Channel events. +::: + ### Examples **Example 1: Single Filter** @@ -151,4 +174,10 @@ Understanding how filters work will help you create effective notification subsc - Filter: License Type = Trial, Paid (both selected) - **Result**: Notification triggers when either trial OR paid customer licenses for MyApp are expiring +**Example 4: License Field Condition Filter** +- Event Type: Instance Upgraded +- Filter: Application = "MyApp" +- License Field Condition: `tier` equals "premium" AND `seats` greater than or equal to 100 +- **Result**: Notification triggers only when instances belonging to premium-tier customers with 100 or more seats are upgraded + diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index 8629d21601..e4667d1245 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -8,44 +8,31 @@ This topic describes how to view, edit, disable, and delete event notifications ## Overview -The Notifications page in the Vendor Portal provides visibility into both personal and team notifications, as well as a complete history of notification events. You can manage your own subscriptions and, if you have the appropriate permissions, view and manage team subscriptions. +The Notifications page in the Vendor Portal provides visibility into your notification subscriptions and, optionally, team subscriptions, as well as a complete history of notification events. You can manage your own subscriptions and, if you have the appropriate permissions, view and manage team subscriptions. ## Viewing Notification Subscriptions -The Notifications list page provides three main views: +The Notifications page provides two main views: -### My Notifications +### Overview -Shows only notifications you created, giving you quick access to manage your personal monitoring setup. +Shows your notification subscriptions. You can optionally include team notifications using the **Show team notifications** checkbox. -To view your notifications: +To view notification subscriptions: -1. Navigate to **Notifications** in the Vendor Portal -2. Select the **My Notifications** tab -3. View the list of your active and inactive subscriptions -4. (Optional) Use the search bar to filter subscriptions by name or event type +1. Navigate to **Notifications** in the Vendor Portal. +2. The **Overview** tab displays your active and inactive subscriptions. +3. (Optional) Select the **Show team notifications** checkbox to include notifications created by other team members. +4. (Optional) Use the search bar to filter subscriptions by name or event type. - + Each subscription card displays the delivery channel (email or webhook), the delivery address, the date created, and who created it. If a custom name is set, it appears as the card title. -### Team Notifications - -Shows all notifications created by anyone on your team. This view is useful for understanding what monitoring is in place across the organization. - -To view team notifications: - -1. Navigate to **Notifications** in the Vendor Portal -2. Select the **Team Notifications** tab -3. View all subscriptions created by team members -4. (Optional) Use the search bar to filter subscriptions by name or event type - **Permissions:** - **Team admins** can manage (edit/delete) any team member's notifications - **Non-admin users** can view team notifications but cannot modify subscriptions created by others - - ### History Shows all triggered notification events for the selected time period. You can filter the history to show only your notifications or filter by a specific notification, including deleted subscriptions. @@ -86,13 +73,11 @@ To modify a notification: 1. Navigate to **Notifications** in the Vendor Portal -2. Find the notification you want to edit in the list: - - Use the **My Notifications** tab for your subscriptions - - Use the **Team Notifications** tab to find any team member's subscription (if you're a team admin) +2. Find the notification you want to edit in the list. Select the **Show team notifications** checkbox if the notification was created by another team member. -3. Click the **Edit** icon or **"Edit"** button for that notification +3. Click the **Edit** icon or **Edit** button for that notification -4. The notification form will open with all current settings populated +4. The notification form opens with all current settings populated 5. Make your desired changes: - Add or update a custom subscription name to help identify the subscription @@ -100,14 +85,14 @@ To modify a notification: - Change the delivery method or destination - Pause/unpause the notification -6. Click **"Save Changes"** to update +6. Click **Save Changes** to update **Important notes:** - Editing a notification does not affect past events already sent - Changes apply immediately to future events -- You can only edit notifications you created, unless you're a team admin with permissions to manage all team notifications +- You can only edit notifications you created, unless you are a team admin with permissions to manage all team notifications ## Disable a Notification @@ -150,7 +135,7 @@ To permanently remove a notification: Each notification maintains a history of when it triggered and what events matched: 1. Navigate to **Notifications** in the Vendor Portal -2. Find the notification in the list (either **My Notifications** or **Team Notifications**) +2. Find the notification in the list. Select the **Show team notifications** checkbox if the notification was created by another team member. 3. Click the **"View History"** button for that notification This filtered view shows only events that matched this specific notification, making it easier to understand the notification's behavior and troubleshoot any issues. diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index f091856e8b..e8c33c3905 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -10,7 +10,7 @@ The ability to set up notifications for key events of interest within Vendor Por Event Notifications allow you to subscribe to specific events and receive alerts via email or webhook. You can create highly targeted notifications using filters to focus on the events that matter most to your workflow. -Event types available are predefined, but these events can cover a broad range of use cases by leveraging available filtering conditions on a given event. +Event types are predefined, but you can cover a broad range of use cases by leveraging available filtering conditions on a given event, including filters by application, customer, channel, license type, and custom license field values (entitlements). Events are queued to SQS for reliable processing and notifications are matched against event filters in real-time. Email notifications are sent via the configured email service, and webhook notifications include HMAC signatures for verification. @@ -73,8 +73,9 @@ Instance related notifications will include the Instance Name if set, otherwise - **Event Type:** Support Bundle Uploaded - **Configuration:** - - Filter - Customer: Select your key enterprise customer (e.g., "Acme Corp", "GlobalTech Inc", "Enterprise Solutions Ltd") - Filter - Application: Select your production application + - Filter - Customer: Select your key enterprise customer (for example, "Acme Corp", "GlobalTech Inc") + - License Field Condition: `tier` equals "Enterprise" AND `seats` greater than or equal to 100 - **Delivery Method:** Email to your work email (or team email alias) ### Sales Manager: Trial License Expiration From 65ca1721facac2d4870a296e54eec5beabc629f6 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Thu, 19 Feb 2026 12:35:10 -0700 Subject: [PATCH 11/23] Document webhook payload preview and test webhook button Adds documentation for the two new webhook features from vandoor PR #8992: - Webhook payload format preview (collapsible JSON structure viewer) - Send test webhook button with success/failure feedback Updates the overview comparison table, create flow, webhooks reference, and local testing sections. Adds screenshot TODO placeholders. Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications-create.mdx | 4 +- docs/vendor/event-notifications-webhooks.mdx | 60 +++++++++++++++++--- docs/vendor/event-notifications.mdx | 1 + 3 files changed, 56 insertions(+), 9 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 70ef069919..954f80ebcc 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -68,7 +68,9 @@ To create a new notification subscription: ### Webhook Delivery - Enter a webhook URL - (Optional) Enter a signing secret for HMAC signature verification - - See [Event Notification Webhooks (Beta)](event-notifications-webhooks) for technical details + - After entering a URL, you can expand the **Webhook payload format** section to preview the exact JSON payload structure your endpoint receives for the selected event type. Click **Copy payload** to copy the format to your clipboard. + - Click **Send test webhook** to send a sample payload to your endpoint and verify connectivity. The test result displays the HTTP status code and response time, or an error message with troubleshooting guidance. If you configured a signing secret, the test request is signed with HMAC-SHA256 so you can also verify your signature validation logic. + - For more information about webhook payload structure, signing, and delivery behavior, see [Configure Event Notification Webhooks (Beta)](event-notifications-webhooks). diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 2984bab694..21b4ef7633 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -12,6 +12,8 @@ Webhooks allow you to receive Event Notifications as HTTP POST requests to an en Event Notifications webhooks include: - JSON payload with event data +- Event-specific payload format preview with copy support +- Built-in test webhook to verify endpoint connectivity before activating - HMAC-SHA256 signature for verification - Automatic retries with exponential backoff - Delivery attempt tracking @@ -34,12 +36,52 @@ To configure a webhook for Event Notifications: - (Optional but recommended) Enter a signing secret for HMAC verification 3. **Test your webhook:** - - Trigger a test event to verify webhook delivery - - Check your endpoint logs for incoming requests - - Verify the payload structure matches your expectations + - Click **Send test webhook** in the notification form to send a sample payload to your endpoint + - The test result displays the HTTP status code and response time on success, or an error message on failure + - You can also expand the **Webhook payload format** section to preview the exact JSON structure your endpoint receives before testing See [Create Event Notification Subscriptions (Beta)](event-notifications-create) for detailed instructions on creating subscriptions. +## Previewing the Webhook Payload Format {#payload-preview} + +When you create or edit a webhook notification and select an event type, you can expand the **Webhook payload format** section in the notification form to see the exact JSON structure your endpoint receives for that event type. + +The preview shows: +- The top-level payload envelope (`event`, `timestamp`, `data`, `text`) +- All event-specific fields in the `data` object, with type annotations (string, number, boolean, ISO-8601-timestamp, array, or object) + +The preview updates dynamically when you change the selected event type. Click **Copy payload** to copy the format to your clipboard, which is useful when building your endpoint's request parser. + + + +## Testing Webhooks {#test-webhook} + +You can test your webhook endpoint directly from the notification form before activating the subscription. This verifies that your endpoint is reachable, responds correctly, and (if a signing secret is configured) that your signature validation logic works. + +To test a webhook: + +1. Enter a webhook URL in the notification form +2. (Optional) Enter a signing secret +3. Click **Send test webhook** + +The test sends an HTTP POST request to your endpoint with a sample payload that matches the structure of a real event. The test result displays: + +- **On success:** The HTTP status code and response time in milliseconds (for example, "200 OK in 120ms") +- **On failure:** An error message describing the issue (for example, network errors, non-2xx status codes, or timeouts) + + + +:::note +Test webhook payloads include a `"test": true` field to distinguish them from real event notifications. The `data` object contains representative sample values (such as "Acme Corp" for customer names) rather than real data from your account. +::: + +### Test Webhook Requirements + +- Your endpoint must be publicly accessible (or reachable through a secure tunnel) +- Your endpoint must respond within 5 seconds with a 2xx status code +- If a signing secret is configured, the test payload is signed with HMAC-SHA256 using the same `X-Replicated-Signature` header as real deliveries +- Private and internal IP addresses (localhost, RFC 1918 ranges, link-local, cloud metadata endpoints) are blocked for security + ## Webhook Payload Structure Event Notifications webhooks deliver a JSON payload with the following structure: @@ -254,19 +296,21 @@ To debug webhook delivery issues: ### Testing Webhooks Locally -To test webhooks during development: +To test webhooks against a local development endpoint: -1. **Use a tunnel service** like ngrok to expose your local endpoint: - ```bash +1. Use a tunnel service like ngrok to expose your local endpoint: + ``` ngrok http 3000 ``` -2. **Use the ngrok URL** as your webhook URL in the notification configuration: +2. Enter the ngrok URL as your webhook URL in the notification form: ``` https://abc123.ngrok.io/webhook ``` -3. **Trigger test events** and watch the ngrok dashboard or your application logs +3. Click **Send test webhook** to send a sample payload to your local endpoint through the tunnel + +4. Check the ngrok dashboard or your application logs to verify the request was received and processed correctly ## Next Steps diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index e8c33c3905..d97dd45e1e 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -28,6 +28,7 @@ Event Notifications offers significant improvements over the classic [Instance N | **Filtering** | Instance-level only | Multi-field filters (app, customer, channel, etc.) | | **Permissions** | User-scoped | Team-scoped RBAC | | **Webhook Security** | Basic | HMAC-SHA256 signing | +| **Webhook Testing** | Manual | Built-in payload preview and test webhook button | | **Notification History** | Minimal | Full delivery attempt tracking with event details | ## Available Event Types From d883e13945c9f6cc57e7c73edd4b93bc059561d7 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Tue, 24 Feb 2026 14:57:11 -0700 Subject: [PATCH 12/23] Added new custom webhook headers feature Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications-create.mdx | 3 ++- docs/vendor/event-notifications-webhooks.mdx | 23 ++++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 954f80ebcc..afa9e9390f 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -68,9 +68,10 @@ To create a new notification subscription: ### Webhook Delivery - Enter a webhook URL - (Optional) Enter a signing secret for HMAC signature verification + - (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint (for example, `Authorization: Bearer token`). For more information, see [Custom HTTP Headers](event-notifications-webhooks#custom-headers). - After entering a URL, you can expand the **Webhook payload format** section to preview the exact JSON payload structure your endpoint receives for the selected event type. Click **Copy payload** to copy the format to your clipboard. - Click **Send test webhook** to send a sample payload to your endpoint and verify connectivity. The test result displays the HTTP status code and response time, or an error message with troubleshooting guidance. If you configured a signing secret, the test request is signed with HMAC-SHA256 so you can also verify your signature validation logic. - - For more information about webhook payload structure, signing, and delivery behavior, see [Configure Event Notification Webhooks (Beta)](event-notifications-webhooks). + - For more information about webhook payload structure, signing, headers, and delivery behavior, see [Configure Event Notification Webhooks (Beta)](event-notifications-webhooks). diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 21b4ef7633..d38c871054 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -14,6 +14,7 @@ Event Notifications webhooks include: - JSON payload with event data - Event-specific payload format preview with copy support - Built-in test webhook to verify endpoint connectivity before activating +- Optional custom HTTP headers for webhook authentication - HMAC-SHA256 signature for verification - Automatic retries with exponential backoff - Delivery attempt tracking @@ -34,6 +35,7 @@ To configure a webhook for Event Notifications: - Choose **Webhook** as the delivery method - Enter your webhook URL - (Optional but recommended) Enter a signing secret for HMAC verification + - (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint. For more information, see [Custom HTTP Headers](#custom-headers). 3. **Test your webhook:** - Click **Send test webhook** in the notification form to send a sample payload to your endpoint @@ -42,6 +44,26 @@ To configure a webhook for Event Notifications: See [Create Event Notification Subscriptions (Beta)](event-notifications-create) for detailed instructions on creating subscriptions. +## Custom HTTP Headers {#custom-headers} + +You can add custom HTTP headers to webhook subscriptions to authenticate with your receiving endpoint. This is useful when your endpoint requires an API key, bearer token, or other credentials in the request headers. + +To add custom headers: + +1. In the webhook notification form, expand **Advanced configuration** +1. Click **Add header** +1. Enter the header name and value +1. (Optional) Repeat to add additional headers + +Custom headers have the following constraints: + +- Maximum of 5 headers per subscription +- Header values can be up to 2048 characters +- Duplicate header names are not allowed +- Certain reserved headers (such as `Content-Type` and `Host`) cannot be overridden + +Header values are encrypted at rest and masked in the UI after you save the subscription. To update a saved header value, you must re-enter it. Custom headers are included in both real webhook deliveries and test webhook requests. + ## Previewing the Webhook Payload Format {#payload-preview} When you create or edit a webhook notification and select an event type, you can expand the **Webhook payload format** section in the notification form to see the exact JSON structure your endpoint receives for that event type. @@ -80,6 +102,7 @@ Test webhook payloads include a `"test": true` field to distinguish them from re - Your endpoint must be publicly accessible (or reachable through a secure tunnel) - Your endpoint must respond within 5 seconds with a 2xx status code - If a signing secret is configured, the test payload is signed with HMAC-SHA256 using the same `X-Replicated-Signature` header as real deliveries +- If custom HTTP headers are configured, they are included in the test request so you can verify your endpoint's authentication logic - Private and internal IP addresses (localhost, RFC 1918 ranges, link-local, cloud metadata endpoints) are blocked for security ## Webhook Payload Structure From fd83087b556381cd51da0ffda86bbfefcfeab304 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Thu, 26 Feb 2026 08:47:04 -0700 Subject: [PATCH 13/23] Added new webhook disable email notification Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications-webhooks.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index d38c871054..7a557954d8 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -277,7 +277,11 @@ A webhook delivery is considered failed when: - The request times out (exceeds 5 seconds) - A network error occurs (endpoint unreachable, DNS failure, etc.) -After all retry attempts are exhausted, the notification is marked as permanently failed and can be viewed in the notification history. +After all retry attempts are exhausted, the notification is marked as permanently failed and can be viewed in the notification history. An email is also sent to the subscription creator and team admins with details about the failure, including the event type, the last error message, and a link to the delivery history in the Vendor Portal. + +### Auto-Disable + +If a webhook subscription has 10 consecutive permanent failures, it is automatically disabled to prevent continued delivery attempts to an unreachable endpoint. To resume deliveries, verify that your endpoint is reachable and then re-enable the subscription from the **Notifications** page. ## Debugging Webhooks {#debugging} From 8a0c06c139154ef6a4c17c8e3b33cf6ee2a52af3 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Sun, 1 Mar 2026 12:30:04 -0700 Subject: [PATCH 14/23] updated for new UI changes Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications-create.mdx | 19 ++++++++++++------- docs/vendor/event-notifications-manage.mdx | 8 ++++---- docs/vendor/event-notifications-webhooks.mdx | 10 +++++----- docs/vendor/event-notifications.mdx | 8 ++++---- 4 files changed, 25 insertions(+), 20 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index afa9e9390f..3a3b617dc4 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -51,11 +51,15 @@ To create a new notification subscription: Subscription names can contain up to 255 ASCII characters (letters, numbers, and basic punctuation). ::: -4. Select an event type from the dropdown +4. Select one or more event types from the categorized event list. Events are grouped by category (Instance, Customer, Support, Release, Channel). Check the checkbox next to each event type you want to include in this subscription. - + -5. Configure filters for the event type. If filters are available for the selected event type, the filter configuration modal opens automatically. For more information about how filters work, see [Filter Logic](#filter-logic). + :::note + A single subscription can include multiple event types. Each selected event type can have its own independent filter configuration. + ::: + +5. (Optional) Configure filters for selected event types. Click the filter icon next to a selected event to open the inline filter configuration panel. Configure your filters, then click **Done** to close the panel. For more information about how filters work, see [Filter Logic](#filter-logic). @@ -69,7 +73,7 @@ To create a new notification subscription: - Enter a webhook URL - (Optional) Enter a signing secret for HMAC signature verification - (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint (for example, `Authorization: Bearer token`). For more information, see [Custom HTTP Headers](event-notifications-webhooks#custom-headers). - - After entering a URL, you can expand the **Webhook payload format** section to preview the exact JSON payload structure your endpoint receives for the selected event type. Click **Copy payload** to copy the format to your clipboard. + - After entering a URL, click **View example** to open the webhook payload preview modal and see the exact JSON payload structure your endpoint receives for the selected event types. Click **Copy payload** to copy the format to your clipboard. - Click **Send test webhook** to send a sample payload to your endpoint and verify connectivity. The test result displays the HTTP status code and response time, or an error message with troubleshooting guidance. If you configured a signing secret, the test request is signed with HMAC-SHA256 so you can also verify your signature validation logic. - For more information about webhook payload structure, signing, headers, and delivery behavior, see [Configure Event Notification Webhooks (Beta)](event-notifications-webhooks). @@ -77,7 +81,7 @@ To create a new notification subscription: 7. Click **"Create Notification"** to activate -Your notification subscription is now active and will begin matching events based on your configured filters. +Your notification subscription is now active and will begin matching events based on your selected event types and configured filters. ## Verify Your Email Address {#email-verification} @@ -113,7 +117,7 @@ Vendor Portal includes an optional AI-assisted notification builder to help you To use the AI builder: -1. Click **"Create with AI"** for guided notification setup +1. Click **"Configure with AI instead"** next to the Name field for guided notification setup 2. Describe in natural language what you want to be notified about - Example: "Notify me when trial customers upload support bundles" - Example: "Alert me when instances fall more than 3 versions behind on the Stable channel" @@ -127,13 +131,14 @@ The AI builder has context of pre-defined event types and filters, but cannot cr ## Filter Logic -Understanding how filters work will help you create effective notification subscriptions. +Understanding how filters work will help you create effective notification subscriptions. Filters are configured per event type — each selected event type in a subscription can have its own independent set of filters. ### Basic Filter Behavior - **No filters specified**: The notification will match **all events** for that event type - **One or more filters specified**: The event must match **all specified filters** to trigger the notification (AND logic) - **Multi-select filters**: If a filter contains multiple selected values, the event must match **any** of the selected values within that filter to trigger the notification (OR logic within the filter) +- **Multiple event types**: When a subscription includes multiple event types, each event type is evaluated independently against its own filters. The subscription triggers when any of the included event types matches its filters. ### License Field Condition Filters diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index e4667d1245..cf12124d02 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -81,9 +81,9 @@ To modify a notification: 5. Make your desired changes: - Add or update a custom subscription name to help identify the subscription - - Modify filters to broaden or narrow the scope + - Add or remove event types, or modify filters on existing event types to broaden or narrow the scope - Change the delivery method or destination - - Pause/unpause the notification + - Check or uncheck the **Enable this notification** checkbox to pause or unpause the notification 6. Click **Save Changes** to update @@ -101,14 +101,14 @@ To temporarily stop a notification without deleting it: 1. Navigate to **Notifications** in the Vendor Portal 2. Find the notification in the list 3. Click the **Edit** button -4. Toggle the notification to **Disabled** state +4. Uncheck the **Enable this notification** checkbox at the bottom of the form 5. Save your changes When a notification is disabled: - It stops triggering for new events - The subscription configuration is preserved - Historical event data remains available -- You can re-enable it at any time by editing and toggling back to active +- You can re-enable it at any time by editing and checking the **Enable this notification** checkbox ## Deleting an Existing Notification diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 7a557954d8..ab2282f433 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -31,7 +31,7 @@ To configure a webhook for Event Notifications: 2. **Create a notification subscription with webhook delivery:** - Navigate to **Notifications** > **Create Notification** - - Select your event type and configure filters + - Select your event types and configure filters - Choose **Webhook** as the delivery method - Enter your webhook URL - (Optional but recommended) Enter a signing secret for HMAC verification @@ -40,7 +40,7 @@ To configure a webhook for Event Notifications: 3. **Test your webhook:** - Click **Send test webhook** in the notification form to send a sample payload to your endpoint - The test result displays the HTTP status code and response time on success, or an error message on failure - - You can also expand the **Webhook payload format** section to preview the exact JSON structure your endpoint receives before testing + - You can also click **View example** to open the payload preview modal and see the exact JSON structure your endpoint receives before testing See [Create Event Notification Subscriptions (Beta)](event-notifications-create) for detailed instructions on creating subscriptions. @@ -66,13 +66,13 @@ Header values are encrypted at rest and masked in the UI after you save the subs ## Previewing the Webhook Payload Format {#payload-preview} -When you create or edit a webhook notification and select an event type, you can expand the **Webhook payload format** section in the notification form to see the exact JSON structure your endpoint receives for that event type. +When you create or edit a webhook notification and select event types, you can click the **View example** button to open the payload preview modal and see the exact JSON structure your endpoint receives. The preview shows: - The top-level payload envelope (`event`, `timestamp`, `data`, `text`) - All event-specific fields in the `data` object, with type annotations (string, number, boolean, ISO-8601-timestamp, array, or object) -The preview updates dynamically when you change the selected event type. Click **Copy payload** to copy the format to your clipboard, which is useful when building your endpoint's request parser. +Click **Copy payload** to copy the format to your clipboard, which is useful when building your endpoint's request parser. @@ -242,7 +242,7 @@ To send Event Notifications to a Slack channel using webhooks: 2. **Create an Event Notification subscription:** - Navigate to **Notifications** > **Create Notification** in the Vendor Portal - - Select your event type and configure filters + - Select your event types and configure filters - Choose **Webhook** as the delivery method - Paste your Slack webhook URL - (Optional) Add a signing secret if you want to verify signatures diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index d97dd45e1e..c466b511bb 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -8,13 +8,13 @@ The ability to set up notifications for key events of interest within Vendor Por ## Overview -Event Notifications allow you to subscribe to specific events and receive alerts via email or webhook. You can create highly targeted notifications using filters to focus on the events that matter most to your workflow. +Event Notifications allow you to subscribe to specific events and receive alerts via email or webhook. A single subscription can include multiple event types, each with its own independent filter configuration. You can create highly targeted notifications using filters to focus on the events that matter most to your workflow. -Event types are predefined, but you can cover a broad range of use cases by leveraging available filtering conditions on a given event, including filters by application, customer, channel, license type, and custom license field values (entitlements). +Event types are predefined and organized by category (Instance, Customer, Support, Release, Channel). You can cover a broad range of use cases by selecting the event types you care about and leveraging available filtering conditions on each event, including filters by application, customer, channel, license type, and custom license field values (entitlements). Events are queued to SQS for reliable processing and notifications are matched against event filters in real-time. Email notifications are sent via the configured email service, and webhook notifications include HMAC signatures for verification. -To get started, review the available event types below, plan your filters based on your workflow needs (by customer, channel, license type, etc.), and choose your delivery method (email or webhook). Then create your first notification using the steps in [Create Event Notification Subscriptions (Beta)](event-notifications-create) and monitor the notification history to refine your filters as needed. +To get started, review the available event types below, plan your filters based on your workflow needs (by customer, channel, license type, etc.), and choose your delivery method (email or webhook). Then create your first subscription using the steps in [Create Event Notification Subscriptions (Beta)](event-notifications-create) and monitor the notification history to refine your event types and filters as needed. ## Comparison: Classic Instance Notifications vs. Event Notifications (Beta) @@ -33,7 +33,7 @@ Event Notifications offers significant improvements over the classic [Instance N ## Available Event Types -Event Notifications initially supports the following high-level event types. Each event type can be further refined using filters to match your specific needs. +Event Notifications supports the following event types, organized by category. Each event type can be further refined using filters to match your specific needs. You can select multiple event types in a single subscription. ### Instance Events - **Instance Created** - When a new instance is created From 0d916cce7fc18f62b244a23f21e7d5c99758b941 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Mon, 2 Mar 2026 16:07:00 -0600 Subject: [PATCH 15/23] updated for recent improvements Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications-create.mdx | 4 ++++ docs/vendor/event-notifications-manage.mdx | 20 ++++++++++++++++++-- docs/vendor/event-notifications-webhooks.mdx | 2 +- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 3a3b617dc4..c8999bc9be 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -61,6 +61,10 @@ To create a new notification subscription: 5. (Optional) Configure filters for selected event types. Click the filter icon next to a selected event to open the inline filter configuration panel. Configure your filters, then click **Done** to close the panel. For more information about how filters work, see [Filter Logic](#filter-logic). + :::note + When configuring a channel filter, you must first select an application. The available channels are filtered to the selected application. + ::: + 6. Choose your notification delivery method: diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index cf12124d02..19af0ea2b1 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -45,6 +45,7 @@ To view notification history: - Filter by time period - Filter to "My Notifications Only" - Filter to a specific notification (active or deleted) + - Filter by delivery status (Delivered, Failed, or Pending) @@ -62,7 +63,7 @@ Event details include: - List of all events that matched this notification's filters - Timestamp when each event occurred - Event details (customer, instance, application, etc.) -- Delivery status (Sent, Failed, Pending) +- Delivery status (Delivered, Failed, Pending) - For failures: Error message explaining why delivery failed This information is helpful for troubleshooting notification delivery issues and understanding which events are triggering your subscriptions. @@ -140,6 +141,21 @@ Each notification maintains a history of when it triggered and what events match This filtered view shows only events that matched this specific notification, making it easier to understand the notification's behavior and troubleshoot any issues. +## Resend a Failed Notification + +If a notification event fails to deliver, you can manually resend it. + +To resend a failed notification: + +1. Navigate to **Notifications** > **History** +1. Find the failed event and expand it +1. Click **Resend email** or **Resend webhook**, depending on the delivery channel +1. Confirm the resend in the confirmation dialog + +:::note +The resend option is only available for events with a Failed delivery status. +::: + ## Troubleshoot Notification Delivery ### Viewing Delivery Status @@ -148,7 +164,7 @@ To check if notifications are being delivered successfully: 1. Navigate to **Notifications** > **History** 2. Look at the **Delivery Status** column for each event: - - **Sent**: Notification was successfully delivered + - **Delivered**: Notification was successfully delivered - **Failed**: Delivery failed (expand row to see error message) - **Pending**: Delivery is in progress or queued diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index ab2282f433..a3e9ecb84a 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -292,7 +292,7 @@ To debug webhook delivery issues: 1. Navigate to **Notifications** > **History** 2. Find the event you're investigating 3. Expand the event row to see: - - Delivery status (Sent, Failed, Pending) + - Delivery status (Delivered, Failed, Pending) - Delivery attempts and timestamps - Error messages for failed attempts - Response status codes from your endpoint From a5bc96781fec4c33b661999e2974a27f1d4e8a02 Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Mon, 2 Mar 2026 16:26:34 -0600 Subject: [PATCH 16/23] Adding new instance state changed and instance state flapping alert. Also updated to Alpha as these will go live slightly ahead of Beta flip Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications-create.mdx | 37 ++++++++++++++--- docs/vendor/event-notifications-manage.mdx | 6 +-- docs/vendor/event-notifications-webhooks.mdx | 12 +++--- docs/vendor/event-notifications.mdx | 43 +++++++++++++++----- sidebars.js | 2 +- 5 files changed, 75 insertions(+), 25 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index c8999bc9be..a92c467973 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -1,7 +1,7 @@ -# Create Event Notification Subscriptions (Beta) +# Create Event Notification Subscriptions (Alpha) :::note -Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +Event Notifications is in Alpha. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. ::: This topic describes how to create event notification subscriptions in the Replicated Vendor Portal. @@ -35,7 +35,7 @@ For teams using [custom RBAC policies](team-management-rbac-configuring#configur ### Webhook Configuration -For webhook delivery, see [Configure Event Notification Webhooks (Beta)](event-notifications-webhooks) to set up your webhook endpoint. +For webhook delivery, see [Configure Event Notification Webhooks (Alpha)](event-notifications-webhooks) to set up your webhook endpoint. ## Create an Event Notification @@ -79,7 +79,7 @@ To create a new notification subscription: - (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint (for example, `Authorization: Bearer token`). For more information, see [Custom HTTP Headers](event-notifications-webhooks#custom-headers). - After entering a URL, click **View example** to open the webhook payload preview modal and see the exact JSON payload structure your endpoint receives for the selected event types. Click **Copy payload** to copy the format to your clipboard. - Click **Send test webhook** to send a sample payload to your endpoint and verify connectivity. The test result displays the HTTP status code and response time, or an error message with troubleshooting guidance. If you configured a signing secret, the test request is signed with HMAC-SHA256 so you can also verify your signature validation logic. - - For more information about webhook payload structure, signing, headers, and delivery behavior, see [Configure Event Notification Webhooks (Beta)](event-notifications-webhooks). + - For more information about webhook payload structure, signing, headers, and delivery behavior, see [Configure Event Notification Webhooks (Alpha)](event-notifications-webhooks). @@ -144,6 +144,33 @@ Understanding how filters work will help you create effective notification subsc - **Multi-select filters**: If a filter contains multiple selected values, the event must match **any** of the selected values within that filter to trigger the notification (OR logic within the filter) - **Multiple event types**: When a subscription includes multiple event types, each event type is evaluated independently against its own filters. The subscription triggers when any of the included event types matches its filters. +### Event-Specific Required Filters + +Some event types require additional configuration beyond the standard optional filters. These required filters appear in the filter configuration panel when the event type is selected. + +**Instance State Duration:** + +This event type requires you to specify the target state and duration threshold. Only one Instance State Duration event is allowed per subscription. + +| Filter | Required | Options | +|--------|----------|---------| +| State | Yes | Ready, Unavailable, Degraded, Updating, Missing | +| Duration | Yes | 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours, 24 hours | + +The notification triggers when an instance has been in the specified state for at least the configured duration. If the instance recovers and later re-enters the monitored state, the notification can trigger again after the duration threshold is met. + +**Instance State Flapping:** + +This event type requires you to specify the sensitivity of flapping detection. + +| Filter | Required | Default | Options | +|--------|----------|---------|---------| +| Minimum State Changes | Yes | — | 3, 5, 10, 15, 20 | +| Time Window | Yes | — | 30 minutes, 1 hour, 2 hours | +| Cooldown Period | No | 1 hour | 15 minutes, 30 minutes, 1 hour, 2 hours, 1 day | + +The notification triggers when an instance accumulates the specified number of state changes within the time window. The cooldown period prevents repeated notifications for the same instance within the configured interval. + ### License Field Condition Filters For customer-related and instance-related events, you can filter notifications based on custom license field (entitlement) values. This allows you to create targeted notifications based on your customers' entitlement data. @@ -160,7 +187,7 @@ When multiple license field conditions are specified, all conditions must match License field conditions are available for the following event types: - All Customer events (Customer Created, Customer Updated, Customer Archived, Customer Unarchived, Customer License Expiring) -- All Instance events (Instance Created, Instance Upgraded, Instance Version Behind, Instance Inactive) +- All Instance events (Instance Created, Instance Upgraded, Instance Version Behind, Instance Inactive, Instance State Duration, Instance State Flapping) - Support Bundle events (Support Bundle Uploaded, Support Bundle Analyzed) :::note diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index 19af0ea2b1..aa7429076d 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -1,7 +1,7 @@ -# Manage Event Notification Subscriptions (Beta) +# Manage Event Notification Subscriptions (Alpha) :::note -Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +Event Notifications is in Alpha. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. ::: This topic describes how to view, edit, disable, and delete event notifications in the Replicated Vendor Portal. @@ -183,7 +183,7 @@ To check if notifications are being delivered successfully: **Webhook endpoint issues:** - Verify webhook URL is correct and accessible - Check that your endpoint returns 2xx status codes -- See [Event Notification Webhooks (Beta)](event-notifications-webhooks) for webhook troubleshooting +- See [Event Notification Webhooks (Alpha)](event-notifications-webhooks) for webhook troubleshooting **RBAC permissions:** - Verify you have the necessary permissions to create and manage notifications diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index a3e9ecb84a..4c1bfaabc1 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -1,7 +1,7 @@ -# Configure Event Notification Webhooks (Beta) +# Configure Event Notification Webhooks (Alpha) :::note -Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +Event Notifications is in Alpha. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. ::: This topic describes how to configure and use webhooks for Event Notifications, including webhook payload structure, HMAC signature verification, and integration with services like Slack. @@ -42,7 +42,7 @@ To configure a webhook for Event Notifications: - The test result displays the HTTP status code and response time on success, or an error message on failure - You can also click **View example** to open the payload preview modal and see the exact JSON structure your endpoint receives before testing -See [Create Event Notification Subscriptions (Beta)](event-notifications-create) for detailed instructions on creating subscriptions. +See [Create Event Notification Subscriptions (Alpha)](event-notifications-create) for detailed instructions on creating subscriptions. ## Custom HTTP Headers {#custom-headers} @@ -341,6 +341,6 @@ To test webhooks against a local development endpoint: ## Next Steps -- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Create webhook subscriptions -- [Manage Event Notification Subscriptions (Beta)](event-notifications-manage) - View webhook delivery history -- [Event Notifications (Beta)](event-notifications) - Overview and available event types +- [Create Event Notification Subscriptions (Alpha)](event-notifications-create) - Create webhook subscriptions +- [Manage Event Notification Subscriptions (Alpha)](event-notifications-manage) - View webhook delivery history +- [Event Notifications (Alpha)](event-notifications) - Overview and available event types diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index c466b511bb..c2c42f0023 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -1,7 +1,7 @@ -# About Event Notifications (Beta) +# About Event Notifications (Alpha) :::note -Event Notifications is in Beta. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +Event Notifications is in Alpha. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. ::: The ability to set up notifications for key events of interest within Vendor Portal can help you proactively manage and prevent issues. @@ -14,15 +14,15 @@ Event types are predefined and organized by category (Instance, Customer, Suppor Events are queued to SQS for reliable processing and notifications are matched against event filters in real-time. Email notifications are sent via the configured email service, and webhook notifications include HMAC signatures for verification. -To get started, review the available event types below, plan your filters based on your workflow needs (by customer, channel, license type, etc.), and choose your delivery method (email or webhook). Then create your first subscription using the steps in [Create Event Notification Subscriptions (Beta)](event-notifications-create) and monitor the notification history to refine your event types and filters as needed. +To get started, review the available event types below, plan your filters based on your workflow needs (by customer, channel, license type, etc.), and choose your delivery method (email or webhook). Then create your first subscription using the steps in [Create Event Notification Subscriptions (Alpha)](event-notifications-create) and monitor the notification history to refine your event types and filters as needed. -## Comparison: Classic Instance Notifications vs. Event Notifications (Beta) +## Comparison: Classic Instance Notifications vs. Event Notifications (Alpha) Event Notifications offers significant improvements over the classic [Instance Notifications (Classic)](instance-notifications-config) system, including more event types, fine-grained filtering, flexible routing to individual or team email addresses or webhooks, notification history tracking, and better access control. -| Feature | Classic Instance Notifications | Event Notifications (Beta) | +| Feature | Classic Instance Notifications | Event Notifications (Alpha) | |---------|------------------------------|---------------------------| -| **Event Types** | 3 types (App Status, System Events, Custom Metrics) | 19+ types across 6 categories | +| **Event Types** | 3 types (App Status, System Events, Custom Metrics) | 21+ types across 6 categories | | **Scope** | Per-instance subscriptions | Team-wide with flexible filtering | | **Delivery** | Slack (1 team webhook) + Email (1 user) | Per notification email or webhook | | **Filtering** | Instance-level only | Multi-field filters (app, customer, channel, etc.) | @@ -39,7 +39,9 @@ Event Notifications supports the following event types, organized by category. E - **Instance Created** - When a new instance is created - **Instance Upgraded** - When an instance upgrades to a new release version - **Instance Version Behind** - When an instance falls behind by a specified number of versions -- **Instance Inactive** - When an instance has not reported in for 24 hours (declared "Inactive") +- **Instance Inactive** - When an instance has not reported in for 24 hours (declared "Inactive"). Air-gapped instances are excluded from this event type. +- **Instance State Duration** - When an instance has been in a specific state (such as Unavailable or Degraded) for a specified duration +- **Instance State Flapping** - When an instance is changing states frequently within a configured time window ### Customer Events - **Customer Created** - When a new customer is created @@ -108,6 +110,27 @@ Instance related notifications will include the Instance Name if set, otherwise - Filter - Asset Type: Any, or narrow further - **Delivery Method:** Email to your work email (or team email alias) +### Support Engineer: Unhealthy Instance Alert +**Scenario:** As a Support Engineer, you want to be notified when a customer instance has been in an unhealthy state for an extended period so that you can proactively reach out. + +- **Event Type:** Instance State Duration +- **Configuration:** + - Filter - State: "Unavailable" + - Filter - Duration: "1 hour" + - Filter - Application: Select your production application + - Filter - License Type: "Paid" +- **Delivery Method:** Webhook to #support-escalations channel in Slack + +### Operations Lead: Instance Instability +**Scenario:** As an Operations Lead, you want to be notified when a customer instance is rapidly changing states, which may indicate an underlying infrastructure or configuration issue. + +- **Event Type:** Instance State Flapping +- **Configuration:** + - Filter - Minimum State Changes: 5 + - Filter - Time Window: 30 minutes + - Filter - Application: Select your application +- **Delivery Method:** Email to `ops-team@example.com` + ## Permissions Event Notifications uses team-scoped RBAC permissions to control access. Your ability to view and manage notifications depends on your role: @@ -132,13 +155,13 @@ Event Notifications uses team-scoped RBAC permissions to control access. Your ab When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. ::: -For detailed information about custom RBAC policies and notification permissions, see [Create Event Notification Subscriptions (Beta)](event-notifications-create). +For detailed information about custom RBAC policies and notification permissions, see [Create Event Notification Subscriptions (Alpha)](event-notifications-create). ## Limitations -Current limitations of Event Notifications (Beta): +Current limitations of Event Notifications (Alpha): -- Event Notifications does not yet cover all instance and custom metric event types from the classic Instance Notifications feature, including Instance health state changed (aka Instance State Changed) +- Event Notifications does not yet cover all instance and custom metric event types from the classic Instance Notifications feature - Notification events generated are not included in the [Instance Bulk Data Export API](instance-data-export) - It is possible to create a notification for some resource types, such as customers and support bundles, but not be able to access the notification linked asset due to your allowed user permissions. This is most likely to impact teams with [enterprise and custom RBAC policies](team-management-rbac-configuring). For example, someone with the [Sales RBAC role](team-management-rbac-configuring) can create a notification for a customer uploading a support bundle, but does not have permission to view the linked specific customer bundle due to their RBAC role permissions. - The Release Assets Downloaded event may fire per chart/image if the customer pulls each separately as part of your installation instructions. As these assets can be shared across many release versions, the access event is recorded at the chart/image level and is not easily identifiable to a specific release version. If you find this alert too noisy, please reach out to us to further discuss your specific use case. diff --git a/sidebars.js b/sidebars.js index 8374fc7cb1..346f04213d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -187,7 +187,7 @@ const sidebars = { "vendor/instance-insights-details", { type: "category", - label: "Event Notifications (Beta)", + label: "Event Notifications (Alpha)", items: [ "vendor/event-notifications", "vendor/event-notifications-create", From dad8bad0d107ade4af41f471f89bc88825dc5bef Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Mon, 2 Mar 2026 16:40:09 -0600 Subject: [PATCH 17/23] Updated classic notifications page Beta references to Alpha and narrowed limitations bullet to custom metrics only Co-Authored-By: Claude Opus 4.6 --- docs/vendor/event-notifications.mdx | 2 +- docs/vendor/instance-notifications-config.mdx | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index c2c42f0023..e65ab315cb 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -161,7 +161,7 @@ For detailed information about custom RBAC policies and notification permissions Current limitations of Event Notifications (Alpha): -- Event Notifications does not yet cover all instance and custom metric event types from the classic Instance Notifications feature +- Event Notifications does not yet cover custom metric change event types from the classic Instance Notifications feature - Notification events generated are not included in the [Instance Bulk Data Export API](instance-data-export) - It is possible to create a notification for some resource types, such as customers and support bundles, but not be able to access the notification linked asset due to your allowed user permissions. This is most likely to impact teams with [enterprise and custom RBAC policies](team-management-rbac-configuring). For example, someone with the [Sales RBAC role](team-management-rbac-configuring) can create a notification for a customer uploading a support bundle, but does not have permission to view the linked specific customer bundle due to their RBAC role permissions. - The Release Assets Downloaded event may fire per chart/image if the customer pulls each separately as part of your installation instructions. As these assets can be shared across many release versions, the access event is recorded at the chart/image level and is not easily identifiable to a specific release version. If you find this alert too noisy, please reach out to us to further discuss your specific use case. diff --git a/docs/vendor/instance-notifications-config.mdx b/docs/vendor/instance-notifications-config.mdx index 5b715f6e3b..e418ff7a56 100644 --- a/docs/vendor/instance-notifications-config.mdx +++ b/docs/vendor/instance-notifications-config.mdx @@ -4,9 +4,9 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-abo # Configure Instance Notifications (Classic) :::caution Classic System -This notification system is being replaced by [Event Notifications (Beta)](event-notifications), which offers more event types, better filtering, and improved delivery options. While this classic system continues to work, we recommend exploring Event Notifications for new notification configurations. +This notification system is being replaced by [Event Notifications (Alpha)](event-notifications), which offers more event types, better filtering, and improved delivery options. While this classic system continues to work, we recommend exploring Event Notifications for new notification configurations. -For a comparison of features, see [Comparison: Classic vs. Event Notifications](event-notifications#comparison-classic-vs-event-notifications-beta). +For a comparison of features, see [Comparison: Classic vs. Event Notifications](event-notifications#comparison-classic-instance-notifications-vs-event-notifications-alpha). ::: @@ -66,6 +66,6 @@ There is a 30-second buffer between event detection and notifications being sent ## See Also -- [Event Notifications (Beta)](event-notifications) - New notification system with more event types and better filtering -- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Get started with Event Notifications -- [Comparison: Classic vs. Event Notifications](event-notifications#comparison-classic-vs-event-notifications-beta) - Feature comparison \ No newline at end of file +- [Event Notifications (Alpha)](event-notifications) - New notification system with more event types and better filtering +- [Create Event Notification Subscriptions (Alpha)](event-notifications-create) - Get started with Event Notifications +- [Comparison: Classic vs. Event Notifications](event-notifications#comparison-classic-instance-notifications-vs-event-notifications-alpha) - Feature comparison \ No newline at end of file From 2e895c9cf6f2ce5c0cdd5b86c614234b041c865e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 3 Mar 2026 13:05:05 -0700 Subject: [PATCH 18/23] docs wip --- docs/vendor/event-notifications-create.mdx | 233 ++++++++----------- docs/vendor/event-notifications-manage.mdx | 2 +- docs/vendor/event-notifications-webhooks.mdx | 2 +- docs/vendor/event-notifications.mdx | 196 ++++++---------- 4 files changed, 166 insertions(+), 267 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index a92c467973..91e1502107 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -1,154 +1,78 @@ # Create Event Notification Subscriptions (Alpha) :::note -Event Notifications is in Alpha. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +Event Notifications is in Alpha. Features and functionality are subject to change. ::: This topic describes how to create event notification subscriptions in the Replicated Vendor Portal. -## Overview +## RBAC Requirements -You can create notification subscriptions from scratch to receive alerts when specific events occur. Each subscription can be customized with filters to target exactly the events that matter to your workflow, and can be delivered via email or webhook. +Users must have the appropriate RBAC permissions to create and manage event notifications. For more information, see [About RBAC Permissions for Event Notifications](#rbac) in _About Event Notifications_. -## Prerequisites - -### RBAC Permissions - -To create and manage Event Notifications, you need appropriate RBAC permissions: - -- **Admin role** - Full access to all notification features including managing other users' subscriptions -- **Read Only role** - Can view all team notifications and their event history, but cannot create notifications -- **Other roles with write access** (Support Engineer, Sales, Custom) - Can create and modify their own notifications; broader team notifications are viewable but not modifiable (read-only) - -:::note -When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. -::: - -For teams using [custom RBAC policies](team-management-rbac-configuring#configure-a-custom-rbac-policy), the following permissions are available: -- `team/notifications/**` - Full access to all notification features including managing other users' subscriptions -- `team/notifications/subscriptions/read` - View all team subscriptions -- `team/notifications/subscriptions/create` - Set up their own alerts -- `team/notifications/subscriptions/update` - Modify their own alerts -- `team/notifications/subscriptions/delete` - Remove their own alerts -- `team/notifications/types/list` - See available event types -- `team/notifications/events/read` - View notification history +## Create an Event Notification -### Webhook Configuration +To create an event notification subscription: -For webhook delivery, see [Configure Event Notification Webhooks (Alpha)](event-notifications-webhooks) to set up your webhook endpoint. +1. (Webhook Only) For webhook delivery, set up a webhook endpoint. See [Configure Event Notification Webhooks (Alpha)](event-notifications-webhooks). -## Create an Event Notification +1. In the Vendor Portal, go to **Notifications**. -To create a new notification subscription: +1. Click **Create Notification**. -1. Navigate to **Notifications** in the Vendor Portal +1. (Optional) Enter a custom name for the subscription. Custom names help you identify subscriptions when you have multiple subscriptions for the same event type. The name is also included in email subjects and webhook payloads. -2. Click **"Create Notification"** + Subscription names can contain up to 255 ASCII characters (letters, numbers, and basic punctuation). -3. (Optional) Enter a custom name for the subscription. Custom names help you identify subscriptions when you have multiple subscriptions for the same event type. The name is also included in email subjects and webhook payloads. +1. Select one or more event types to include in the subscription. :::note - Subscription names can contain up to 255 ASCII characters (letters, numbers, and basic punctuation). + Alternatively, click **Configure with AI instead**. With the AI-assisted notification builder, you can describe in natural language the events that you want to be notified about. For example, "Notify me when trial customers upload support bundles" or "Alert me when instances fall more than 3 versions behind on the Stable channel". The AI builder has context of pre-defined event types and filters, but cannot create new event types or filters. ::: -4. Select one or more event types from the categorized event list. Events are grouped by category (Instance, Customer, Support, Release, Channel). Check the checkbox next to each event type you want to include in this subscription. - - :::note - A single subscription can include multiple event types. Each selected event type can have its own independent filter configuration. - ::: - -5. (Optional) Configure filters for selected event types. Click the filter icon next to a selected event to open the inline filter configuration panel. Configure your filters, then click **Done** to close the panel. For more information about how filters work, see [Filter Logic](#filter-logic). +1. (Optional) For each of the event types that you selected, click the filter icon to configure event filters. For more information about event filters, see [Filter Logic](#filter-logic) on this page. :::note - When configuring a channel filter, you must first select an application. The available channels are filtered to the selected application. + To configure a channel filter, you must first select an application. ::: - - -6. Choose your notification delivery method: +1. Click **Done**. - ### Email Delivery - - Enter an email address - - Email addresses other than your Vendor Portal account email require verification (see [Email Verification](#email-verification) below) + - ### Webhook Delivery - - Enter a webhook URL - - (Optional) Enter a signing secret for HMAC signature verification - - (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint (for example, `Authorization: Bearer token`). For more information, see [Custom HTTP Headers](event-notifications-webhooks#custom-headers). - - After entering a URL, click **View example** to open the webhook payload preview modal and see the exact JSON payload structure your endpoint receives for the selected event types. Click **Copy payload** to copy the format to your clipboard. - - Click **Send test webhook** to send a sample payload to your endpoint and verify connectivity. The test result displays the HTTP status code and response time, or an error message with troubleshooting guidance. If you configured a signing secret, the test request is signed with HMAC-SHA256 so you can also verify your signature validation logic. - - For more information about webhook payload structure, signing, headers, and delivery behavior, see [Configure Event Notification Webhooks (Alpha)](event-notifications-webhooks). +1. Do one of the following, depending on your notification delivery method: + * For email delivery, enter an email address. + * For webhook delivery: + 1. Enter a webhook URL. + 1. (Optional) Enter a signing secret for HMAC signature verification + 1. (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint (for example, `Authorization: Bearer token`). For more information, see [Custom HTTP Headers](event-notifications-webhooks#custom-headers). + 1. After entering a URL, click **View example** to open the webhook payload preview modal and see the exact JSON payload structure your endpoint receives for the selected event types. Click **Copy payload** to copy the format to your clipboard. + 1. Click **Send test webhook** to send a sample payload to your endpoint and verify connectivity. The test result displays the HTTP status code and response time, or an error message with troubleshooting guidance. If you configured a signing secret, the test request is signed with HMAC-SHA256 so you can also verify your signature validation logic. -7. Click **"Create Notification"** to activate - -Your notification subscription is now active and will begin matching events based on your selected event types and configured filters. - -## Verify Your Email Address {#email-verification} - -When sending to an email address other than the one associated with your Vendor Portal user account, you must first validate that email before notifications can be sent. - -### Verification Process - -1. After creating a notification with an unverified email address, a verification email will be sent to that address -2. The notification subscription will be created but remain inactive until verified -3. To complete verification, you have two options: - - **Option 1: Email Link** - - Open the verification email - - Click the validation link in the email - - You must be logged into Vendor Portal in your browser to validate - - **Option 2: Verification Code** - - Copy the verification code from the email - - Navigate to **Notifications** in the Vendor Portal - - Edit the notification subscription - - Enter the verification code - - Save the notification - -4. Once verified, the notification subscription will become active and begin sending notifications +1. Click **Create Notification**. -:::note -You must be logged into Vendor Portal to validate email addresses. -::: - -## AI-Assisted Notification Builder (Optional) - -Vendor Portal includes an optional AI-assisted notification builder to help you quickly set up subscriptions. - -To use the AI builder: - -1. Click **"Configure with AI instead"** next to the Name field for guided notification setup -2. Describe in natural language what you want to be notified about - - Example: "Notify me when trial customers upload support bundles" - - Example: "Alert me when instances fall more than 3 versions behind on the Stable channel" -3. The AI will suggest the appropriate event type and filters based on your description -4. Review and adjust the AI's suggestions before creating -5. Proceed with the standard creation workflow - -:::note -The AI builder has context of pre-defined event types and filters, but cannot create new event types or filters beyond what's available in the system. -::: +1. For email subscriptions, if you used an email address other than your Vendor Portal user account email, follow the instructions in the verification email to validate the email address. ## Filter Logic -Understanding how filters work will help you create effective notification subscriptions. Filters are configured per event type — each selected event type in a subscription can have its own independent set of filters. +Filters are configured per event type. Each selected event type in a notification subscription can have its own independent set of filters. For subscriptions that include multiple event types, each event type is evaluated independently against its own filters. In this case, any events of the included types that matches its filters triggers a notification. + +The following describes the filter logic used for each event: -### Basic Filter Behavior +- **No filters**: Any event of the given type triggers the notification. +- **One or more filters**: An event must match _all_ specified filters (AND logic) to trigger the notification. -- **No filters specified**: The notification will match **all events** for that event type -- **One or more filters specified**: The event must match **all specified filters** to trigger the notification (AND logic) -- **Multi-select filters**: If a filter contains multiple selected values, the event must match **any** of the selected values within that filter to trigger the notification (OR logic within the filter) -- **Multiple event types**: When a subscription includes multiple event types, each event type is evaluated independently against its own filters. The subscription triggers when any of the included event types matches its filters. +If a filter contains multiple selected values, the event must match _any_ of the selected values (OR logic) to satisfy the filter. ### Event-Specific Required Filters Some event types require additional configuration beyond the standard optional filters. These required filters appear in the filter configuration panel when the event type is selected. -**Instance State Duration:** +#### Instance State Duration This event type requires you to specify the target state and duration threshold. Only one Instance State Duration event is allowed per subscription. @@ -159,7 +83,7 @@ This event type requires you to specify the target state and duration threshold. The notification triggers when an instance has been in the specified state for at least the configured duration. If the instance recovers and later re-enters the monitored state, the notification can trigger again after the duration threshold is met. -**Instance State Flapping:** +#### Instance State Flapping This event type requires you to specify the sensitivity of flapping detection. @@ -175,6 +99,8 @@ The notification triggers when an instance accumulates the specified number of s For customer-related and instance-related events, you can filter notifications based on custom license field (entitlement) values. This allows you to create targeted notifications based on your customers' entitlement data. +**Limitation:** License field conditions are not available for Pending Self-Service Signup, Release, or Channel events. + License field conditions use a three-part structure: field, operator, and value. The available operators depend on the field type: | Field Type | Available Operators | @@ -190,33 +116,72 @@ License field conditions are available for the following event types: - All Instance events (Instance Created, Instance Upgraded, Instance Version Behind, Instance Inactive, Instance State Duration, Instance State Flapping) - Support Bundle events (Support Bundle Uploaded, Support Bundle Analyzed) -:::note -License field conditions are not available for Pending Self-Service Signup, Release, or Channel events. -::: +## Event Notification Examples + +The following are example event notifications based on common use cases. + +### Customer Success Manager: Support Bundle Uploaded + +As a Customer Success Manager, I want to be notified if one of my key customers uploads a support bundle. + +- **Event Type:** Support Bundle Uploaded +- **Configuration:** + - Filter - Application: Select your production application + - Filter - Customer: Select your key enterprise customer (for example, "Acme Corp", "GlobalTech Inc") + - License Field Condition: `tier` equals "Enterprise" AND `seats` greater than or equal to 100 +- **Delivery Method:** Email to your work email (or team email alias) + +### Sales Manager: Trial License Expiration + +As a Sales Manager, I want to be notified when a trial customer has an impending trial license expiration. + +- **Event Type:** Customer License Expiring +- **Configuration:** + - Filter - Application: Select your production application + - Filter - License Type: "Trial" +- **Delivery Method:** Email to your work email (or team email alias) + +### Product Manager: Release Promoted + +As a Product Manager, I want to be notified when a new release version is made available to customers on the Stable channel so that I can engage key customers in adoption follow-up conversations. + +- **Event Type:** Release Promoted +- **Configuration:** + - Filter - Application: Select your application + - Filter - Channel: Select "Stable" +- **Delivery Method:** Email to `pm-team@company.com` or webhook to #pm-team channel in Slack + +### Development Leader: Paid Customer Downloads Release Assets + +As a Development Leader, I want to be notified when a paid customer pulls release assets to initiate a paid install. + +- **Event Type:** Release Asset Downloaded +- **Configuration:** + - Filter - Application: Select your application + - Filter - Channel: Select "Stable" + - Filter - License Type: "Paid" + - Filter - Asset Type: Any, or narrow further +- **Delivery Method:** Email to your work email (or team email alias) -### Examples +### Support Engineer: Unhealthy Instance Alert -**Example 1: Single Filter** -- Event Type: Customer Created -- Filter: License Type = Trial -- **Result**: Notification triggers for all trial customer creations +As a Support Engineer, you want to be notified when a customer instance has been in an unhealthy state for an extended period so that you can proactively reach out. -**Example 2: Multiple Filters (AND logic)** -- Event Type: Instance Upgraded -- Filter: Application = "MyApp" -- Filter: Channel = "Stable" -- **Result**: Notification triggers only when instances of MyApp on the Stable channel are upgraded +- **Event Type:** Instance State Duration +- **Configuration:** + - Filter - State: "Unavailable" + - Filter - Duration: "1 hour" + - Filter - Application: Select your production application + - Filter - License Type: "Paid" +- **Delivery Method:** Webhook to #support-escalations channel in Slack -**Example 3: Multi-Select Filter (OR logic within filter)** -- Event Type: Customer License Expiring -- Filter: Application = "MyApp" -- Filter: License Type = Trial, Paid (both selected) -- **Result**: Notification triggers when either trial OR paid customer licenses for MyApp are expiring +### Operations Lead: Instance Instability -**Example 4: License Field Condition Filter** -- Event Type: Instance Upgraded -- Filter: Application = "MyApp" -- License Field Condition: `tier` equals "premium" AND `seats` greater than or equal to 100 -- **Result**: Notification triggers only when instances belonging to premium-tier customers with 100 or more seats are upgraded +As an Operations Lead, you want to be notified when a customer instance is rapidly changing states, which may indicate an underlying infrastructure or configuration issue. - +- **Event Type:** Instance State Flapping +- **Configuration:** + - Filter - Minimum State Changes: 5 + - Filter - Time Window: 30 minutes + - Filter - Application: Select your application +- **Delivery Method:** Email to `ops-team@example.com` diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index aa7429076d..e5b11e7dd8 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -1,7 +1,7 @@ # Manage Event Notification Subscriptions (Alpha) :::note -Event Notifications is in Alpha. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +Event Notifications is in Alpha. Features and functionality are subject to change. ::: This topic describes how to view, edit, disable, and delete event notifications in the Replicated Vendor Portal. diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 4c1bfaabc1..74b341720c 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -1,7 +1,7 @@ # Configure Event Notification Webhooks (Alpha) :::note -Event Notifications is in Alpha. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +Event Notifications is in Alpha. Features and functionality are subject to change. ::: This topic describes how to configure and use webhooks for Event Notifications, including webhook payload structure, HMAC signature verification, and integration with services like Slack. diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index e65ab315cb..01e29afba5 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -1,171 +1,105 @@ # About Event Notifications (Alpha) :::note -Event Notifications is in Alpha. Features and functionality are subject to change as we continue to iterate this functionality towards General Availability. +Event Notifications is in Alpha. Features and functionality are subject to change. ::: -The ability to set up notifications for key events of interest within Vendor Portal can help you proactively manage and prevent issues. +This topic provides an introduction to the Event Notifications (Alpha) feature, which allows you to set up notifications for key events from the Vendor Portal. ## Overview -Event Notifications allow you to subscribe to specific events and receive alerts via email or webhook. A single subscription can include multiple event types, each with its own independent filter configuration. You can create highly targeted notifications using filters to focus on the events that matter most to your workflow. +Event Notifications allow you to subscribe to specific events and receive alerts through email or webhook. A single subscription can include multiple event types, each with its own independent filter configuration. You can create highly-targeted notifications using filters to focus on the events that matter most to your workflow. -Event types are predefined and organized by category (Instance, Customer, Support, Release, Channel). You can cover a broad range of use cases by selecting the event types you care about and leveraging available filtering conditions on each event, including filters by application, customer, channel, license type, and custom license field values (entitlements). +Event types are predefined and organized by category (Instance, Customer, Support, Release, Channel). You can also filter events by application, customer, channel, license type, and your custom license field values (entitlements). -Events are queued to SQS for reliable processing and notifications are matched against event filters in real-time. Email notifications are sent via the configured email service, and webhook notifications include HMAC signatures for verification. +Events are queued to SQS for reliable processing, and notifications are matched against event filters in real-time. Email notifications are sent through the email service that you configure. Webhook notifications include HMAC signatures for verification. -To get started, review the available event types below, plan your filters based on your workflow needs (by customer, channel, license type, etc.), and choose your delivery method (email or webhook). Then create your first subscription using the steps in [Create Event Notification Subscriptions (Alpha)](event-notifications-create) and monitor the notification history to refine your event types and filters as needed. - -## Comparison: Classic Instance Notifications vs. Event Notifications (Alpha) - -Event Notifications offers significant improvements over the classic [Instance Notifications (Classic)](instance-notifications-config) system, including more event types, fine-grained filtering, flexible routing to individual or team email addresses or webhooks, notification history tracking, and better access control. - -| Feature | Classic Instance Notifications | Event Notifications (Alpha) | -|---------|------------------------------|---------------------------| -| **Event Types** | 3 types (App Status, System Events, Custom Metrics) | 21+ types across 6 categories | -| **Scope** | Per-instance subscriptions | Team-wide with flexible filtering | -| **Delivery** | Slack (1 team webhook) + Email (1 user) | Per notification email or webhook | -| **Filtering** | Instance-level only | Multi-field filters (app, customer, channel, etc.) | -| **Permissions** | User-scoped | Team-scoped RBAC | -| **Webhook Security** | Basic | HMAC-SHA256 signing | -| **Webhook Testing** | Manual | Built-in payload preview and test webhook button | -| **Notification History** | Minimal | Full delivery attempt tracking with event details | +To get started, review the (Available Event Types)[#available-event-types] below, design event filters based on what matters most to you, and choose your notification delivery method. Then, create your first subscription. For more information, see [Create Event Notification Subscriptions (Alpha)](event-notifications-create). ## Available Event Types -Event Notifications supports the following event types, organized by category. Each event type can be further refined using filters to match your specific needs. You can select multiple event types in a single subscription. +Event Notifications (Alpha) supports the following event types, organized by category. You can further refine each event type using filters to match your specific needs. You can also select multiple event types in a single subscription. ### Instance Events -- **Instance Created** - When a new instance is created -- **Instance Upgraded** - When an instance upgrades to a new release version -- **Instance Version Behind** - When an instance falls behind by a specified number of versions -- **Instance Inactive** - When an instance has not reported in for 24 hours (declared "Inactive"). Air-gapped instances are excluded from this event type. -- **Instance State Duration** - When an instance has been in a specific state (such as Unavailable or Degraded) for a specified duration -- **Instance State Flapping** - When an instance is changing states frequently within a configured time window +- **Instance Created**: When a new instance is created +- **Instance Upgraded**: When an instance upgrades to a new release version +- **Instance Version Behind**: When an instance falls behind by a specified number of versions +- **Instance Inactive**: When an instance has not reported in for 24 hours (declared "Inactive"). Air-gapped instances are excluded from this event type. +- **Instance State Duration**: When an instance has been in a specific state (such as Unavailable or Degraded) for a specified duration +- **Instance State Flapping**: When an instance is changing states frequently within a configured time window + +:::note +Instance event notifications use the **Instance Name** if set. Otherwise, they use the Instance ID. +::: ### Customer Events -- **Customer Created** - When a new customer is created -- **Customer Updated** - When a customer's details or license is updated -- **Customer Archived** - When a customer is archived -- **Customer Unarchived (Restored)** - When a customer is restored from archived state -- **Customer License Expiring** - Time-based warning of an upcoming license expiration -- **Pending Self-Service Signup** - When someone signs up via the self-service portal (if enabled) +- **Customer Created**: When a new customer is created +- **Customer Updated**: When a customer's details or license is updated +- **Customer Archived**: When a customer is archived +- **Customer Unarchived (Restored)**: When a customer is restored from archived state +- **Customer License Expiring**: Time-based warning of an upcoming license expiration +- **Pending Self-Service Signup**: When someone signs up via the self-service portal (if enabled) ### Support Events -- **Support Bundle Uploaded** - When a support bundle is uploaded -- **Support Bundle Analyzed** - When a support bundle analysis is completed +- **Support Bundle Uploaded**: When a support bundle is uploaded +- **Support Bundle Analyzed**: When a support bundle analysis is completed ### Release Events -- **Release Created** - When a new release is created -- **Release Promoted** - When a release is promoted to a channel -- **Release Demoted (Unpublished)** - When a release is demoted from a channel -- **Release Assets Downloaded** - When a release asset (such as a Helm chart or .tgz bundle) is pulled by a customer +- **Release Created**: When a new release is created +- **Release Promoted**: When a release is promoted to a channel +- **Release Demoted (Unpublished)**: When a release is demoted from a channel +- **Release Assets Downloaded**: When a release asset (such as a Helm chart or .tgz bundle) is pulled by a customer ### Channel Events -- **Channel Created** - When a new channel is created for an application -- **Channel Archived** - When a channel is archived +- **Channel Created**: When a new channel is created for an application +- **Channel Archived**: When a channel is archived -:::note -Instance related notifications will include the Instance Name if set, otherwise it will contain the Instance ID. -::: -## Use Case Examples - -### Customer Success Manager: Key Customer Support Bundle -**Scenario:** As a Customer Success Manager, I want to be notified if one of my key customers uploads a support bundle. - -- **Event Type:** Support Bundle Uploaded -- **Configuration:** - - Filter - Application: Select your production application - - Filter - Customer: Select your key enterprise customer (for example, "Acme Corp", "GlobalTech Inc") - - License Field Condition: `tier` equals "Enterprise" AND `seats` greater than or equal to 100 -- **Delivery Method:** Email to your work email (or team email alias) - -### Sales Manager: Trial License Expiration -**Scenario:** As a Sales Manager, I want to be notified when a trial customer has an impending trial license expiration. - -- **Event Type:** Customer License Expiring -- **Configuration:** - - Filter - Application: Select your production application - - Filter - License Type: "Trial" -- **Delivery Method:** Email to your work email (or team email alias) - -### Product Manager: Release Promotion -**Scenario:** As a Product Manager, I want to be notified when a new release version is made available to customers on the Stable channel so that I can engage key customers in adoption follow-up conversations. - -- **Event Type:** Release Promoted -- **Configuration:** - - Filter - Application: Select your application - - Filter - Channel: Select "Stable" -- **Delivery Method:** Email to `pm-team@company.com` or webhook to #pm-team channel in Slack - -### Development Leader: Paid Customer Installations -**Scenario:** As a Development Leader, I want to be notified when a paid customer pulls release assets to initiate a paid install. - -- **Event Type:** Release Asset Downloaded -- **Configuration:** - - Filter - Application: Select your application - - Filter - Channel: Select "Stable" - - Filter - License Type: "Paid" - - Filter - Asset Type: Any, or narrow further -- **Delivery Method:** Email to your work email (or team email alias) - -### Support Engineer: Unhealthy Instance Alert -**Scenario:** As a Support Engineer, you want to be notified when a customer instance has been in an unhealthy state for an extended period so that you can proactively reach out. - -- **Event Type:** Instance State Duration -- **Configuration:** - - Filter - State: "Unavailable" - - Filter - Duration: "1 hour" - - Filter - Application: Select your production application - - Filter - License Type: "Paid" -- **Delivery Method:** Webhook to #support-escalations channel in Slack - -### Operations Lead: Instance Instability -**Scenario:** As an Operations Lead, you want to be notified when a customer instance is rapidly changing states, which may indicate an underlying infrastructure or configuration issue. - -- **Event Type:** Instance State Flapping -- **Configuration:** - - Filter - Minimum State Changes: 5 - - Filter - Time Window: 30 minutes - - Filter - Application: Select your application -- **Delivery Method:** Email to `ops-team@example.com` - -## Permissions +## About RBAC Permissions for Event Notifications {#rbac} Event Notifications uses team-scoped RBAC permissions to control access. Your ability to view and manage notifications depends on your role: -### Admin Role -- Can manage any team-created notifications in addition to their own -- Can modify, delete, and turn off/on any notification -- Full access to all notification features +- **Admin**: Full access to all notification features including managing other users' subscriptions. +- **Other roles with write access (Support Engineer, Sales, or custom roles)**: Can create and modify their own notifications. Read-only access to team notifications. +- **Read Only**: Can view all team notifications and their event history, but cannot create notifications. -### Read Only Role -- Cannot create notifications -- Can view all team notifications and their event history -- No modification permissions + For teams that use custom RBAC policies, the following permissions are available: + - `team/notifications/**`: Full access to all notification features including managing other users' subscriptions + - `team/notifications/subscriptions/read`: View all team subscriptions + - `team/notifications/subscriptions/create`: Set up their own alerts + - `team/notifications/subscriptions/update`: Modify their own alerts + - `team/notifications/subscriptions/delete`: Remove their own alerts + - `team/notifications/types/list`: See available event types + - `team/notifications/events/read`: View notification history -### Other Non-Admin Roles with Write Access -(Examples: Support Engineer, Sales, Custom roles) -- Can create and modify their own notifications -- Broader team notifications are viewable but not modifiable (read-only) -- Cannot edit or delete notifications created by other team members + For more information, see [Configure RBAC Policies](team-management-rbac-configuring#configure-a-custom-rbac-policy). :::note When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. ::: -For detailed information about custom RBAC policies and notification permissions, see [Create Event Notification Subscriptions (Alpha)](event-notifications-create). +## Comparison to Instance Notifications (Classic) -## Limitations +Event Notifications (Alpha) is the next generation of instance notification functionality in the Vendor Portal. Compared to [Instance Notifications (Classic)](instance-notifications-config), Event Notifications offers more event types, fine-grained filtering, flexible routing to individual or team email addresses or webhooks, notification history tracking, and better access control. -Current limitations of Event Notifications (Alpha): +You can use Event Notifications (Alpha) concurrently with Instance Notifications (Classic) while you evaluate and transition. -- Event Notifications does not yet cover custom metric change event types from the classic Instance Notifications feature -- Notification events generated are not included in the [Instance Bulk Data Export API](instance-data-export) -- It is possible to create a notification for some resource types, such as customers and support bundles, but not be able to access the notification linked asset due to your allowed user permissions. This is most likely to impact teams with [enterprise and custom RBAC policies](team-management-rbac-configuring). For example, someone with the [Sales RBAC role](team-management-rbac-configuring) can create a notification for a customer uploading a support bundle, but does not have permission to view the linked specific customer bundle due to their RBAC role permissions. -- The Release Assets Downloaded event may fire per chart/image if the customer pulls each separately as part of your installation instructions. As these assets can be shared across many release versions, the access event is recorded at the chart/image level and is not easily identifiable to a specific release version. If you find this alert too noisy, please reach out to us to further discuss your specific use case. +The following table compares the functionality offered by Instance Notifications (Classic) and Event Notifications (Alpha): -:::note -Event Notifications can be used concurrently with the classic Instance Notifications system while you evaluate and transition. -::: +| Feature | Instance Notifications (Classic) | Event Notifications (Alpha) | +|---------|------------------------------|---------------------------| +| **Event Types** | Three event types: App Status, System Events, Custom Metrics | More than 20 event types across six categories | +| **Scope** | Per-instance subscriptions | Team-wide with flexible filtering | +| **Delivery** | Slack (1 team webhook) + Email (1 user) | Per notification email or webhook | +| **Filtering** | Instance-level only | Multi-field filters (app, customer, channel, etc.) | +| **Permissions** | User-scoped | Team-scoped RBAC | +| **Webhook Security** | Basic | HMAC-SHA256 signing | +| **Webhook Testing** | Manual | Built-in payload preview and test webhook button | +| **Notification History** | Minimal | Full delivery attempt tracking with event details | + +## Limitations + +- Event Notifications (Alpha) does not support notifying on custom metric change event types +- Notification events generated are not included in the [Instance Bulk Data Export API](instance-data-export) +- It is possible to create a notification for some resource types, such as customers and support bundles, but not to access the notification linked asset due to your allowed user permissions. This is most likely to impact teams with [enterprise and custom RBAC policies](team-management-rbac-configuring). For example, someone with the [Sales RBAC role](team-management-rbac-configuring) can create a notification for a customer uploading a support bundle, but does not have permission to view the linked specific customer bundle due to their RBAC role permissions. +- The Release Assets Downloaded event might fire per chart or image if the customer pulls each separately as part of your installation instructions. As these assets can be shared across many release versions, the access event is recorded at the chart/image level and is not easily identifiable to a specific release version. If you find this alert too noisy, please reach out to us to further discuss your specific use case. From 9df3c03d2ad27a3bb210f1c110964cdb729d0e4b Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 3 Mar 2026 15:19:27 -0700 Subject: [PATCH 19/23] docs edits --- docs/vendor/event-notifications-create.mdx | 104 +++++-- docs/vendor/event-notifications-manage.mdx | 171 +++--------- docs/vendor/event-notifications-webhooks.mdx | 273 ++++++------------- docs/vendor/event-notifications.mdx | 64 +---- 4 files changed, 206 insertions(+), 406 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 91e1502107..aa2f4256b7 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -8,14 +8,25 @@ This topic describes how to create event notification subscriptions in the Repli ## RBAC Requirements -Users must have the appropriate RBAC permissions to create and manage event notifications. For more information, see [About RBAC Permissions for Event Notifications](#rbac) in _About Event Notifications_. +Roles with write access (Admin, Support Engineer, Sales, or custom roles) can create and manage their own notifications. They can also view team notifications. + +Only Admins can create and manage team notifications. Admins can also manage notifications created by other team members. + +For teams that use custom RBAC policies, the following permissions are available: +- `team/notifications/**`: Full access to all notification features including managing other users' subscriptions +- `team/notifications/subscriptions/read`: View all team subscriptions +- `team/notifications/subscriptions/create`: Set up their own alerts +- `team/notifications/subscriptions/update`: Modify their own alerts +- `team/notifications/subscriptions/delete`: Remove their own alerts +- `team/notifications/types/list`: See available event types +- `team/notifications/events/read`: View notification history + +For more information, see [Configure RBAC Policies](team-management-rbac-configuring#configure-a-custom-rbac-policy). ## Create an Event Notification To create an event notification subscription: -1. (Webhook Only) For webhook delivery, set up a webhook endpoint. See [Configure Event Notification Webhooks (Alpha)](event-notifications-webhooks). - 1. In the Vendor Portal, go to **Notifications**. 1. Click **Create Notification**. @@ -24,7 +35,7 @@ To create an event notification subscription: Subscription names can contain up to 255 ASCII characters (letters, numbers, and basic punctuation). -1. Select one or more event types to include in the subscription. +1. Select one or more event types to include in the subscription. For more information, see [Event Types](#event-types) on this page. :::note Alternatively, click **Configure with AI instead**. With the AI-assisted notification builder, you can describe in natural language the events that you want to be notified about. For example, "Notify me when trial customers upload support bundles" or "Alert me when instances fall more than 3 versions behind on the Stable channel". The AI builder has context of pre-defined event types and filters, but cannot create new event types or filters. @@ -32,7 +43,7 @@ To create an event notification subscription: -1. (Optional) For each of the event types that you selected, click the filter icon to configure event filters. For more information about event filters, see [Filter Logic](#filter-logic) on this page. +1. (Optional) For each of the event types that you selected, click the filter icon to configure event filters. For more information, see [Event Filter Logic and Requirements](#filter-logic) on this page. :::note To configure a channel filter, you must first select an application. @@ -45,7 +56,11 @@ To create an event notification subscription: 1. Do one of the following, depending on your notification delivery method: * For email delivery, enter an email address. * For webhook delivery: - 1. Enter a webhook URL. + 1. Enter a webhook URL. The endpoint must meet the following requirements: + - Must be able to receive HTTP POST requests + - Must be publicly accessible (or use a secure tunnel for testing) + - Must respond with a 2xx status code (200-299) for successful delivery + - Response time must be less than five seconds 1. (Optional) Enter a signing secret for HMAC signature verification 1. (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint (for example, `Authorization: Bearer token`). For more information, see [Custom HTTP Headers](event-notifications-webhooks#custom-headers). 1. After entering a URL, click **View example** to open the webhook payload preview modal and see the exact JSON payload structure your endpoint receives for the selected event types. Click **Copy payload** to copy the format to your clipboard. @@ -57,9 +72,54 @@ To create an event notification subscription: 1. For email subscriptions, if you used an email address other than your Vendor Portal user account email, follow the instructions in the verification email to validate the email address. -## Filter Logic +## Event Types + +Event Notifications (Alpha) supports the following event types, organized by category. You can further refine each event type using filters to match your specific needs. You can also select multiple event types in a single subscription. + +### Instance Events +- **Instance Created**: When a new instance is created +- **Instance Upgraded**: When an instance upgrades to a new release version +- **Instance Version Behind**: When an instance falls behind by a specified number of versions +- **Instance Inactive**: When an instance has not reported in for 24 hours (declared "Inactive"). Air-gapped instances are excluded from this event type. +- **Instance State Duration**: When an instance has been in a specific state (such as Unavailable or Degraded) for a specified duration +- **Instance State Flapping**: When an instance is changing states frequently within a configured time window + +:::note +Instance event notifications use the **Instance Name** if set. Otherwise, they use the Instance ID. +::: + +### Customer Events +- **Customer Created**: When a new customer is created +- **Customer Updated**: When a customer's details or license is updated +- **Customer Archived**: When a customer is archived +- **Customer Unarchived (Restored)**: When a customer is restored from archived state +- **Customer License Expiring**: Time-based warning of an upcoming license expiration +- **Pending Self-Service Signup**: When someone signs up via the self-service portal (if enabled) + +### Support Events +- **Support Bundle Uploaded**: When a support bundle is uploaded +- **Support Bundle Analyzed**: When a support bundle analysis is completed + +### Release Events +- **Release Created**: When a new release is created +- **Release Promoted**: When a release is promoted to a channel +- **Release Demoted (Unpublished)**: When a release is demoted from a channel +- **Release Assets Downloaded**: When a release asset (such as a Helm chart or .tgz bundle) is pulled by a customer -Filters are configured per event type. Each selected event type in a notification subscription can have its own independent set of filters. For subscriptions that include multiple event types, each event type is evaluated independently against its own filters. In this case, any events of the included types that matches its filters triggers a notification. +### Channel Events +- **Channel Created**: When a new channel is created for an application +- **Channel Archived**: When a channel is archived + + +## Event Filter Logic and Requirements + +This section describes how per-event filtering works in notification subscriptions. It also describes filter requirements for different types of events. + +### Filter Logic + +Each event type that you select in a notification subscription has its own set of filters. + +For subscriptions that include multiple event types, each event type is evaluated independently against its filters. In this case, any events of the included types that matches its filters triggers a notification. The following describes the filter logic used for each event: @@ -68,13 +128,9 @@ The following describes the filter logic used for each event: If a filter contains multiple selected values, the event must match _any_ of the selected values (OR logic) to satisfy the filter. -### Event-Specific Required Filters +### Instance State Duration Filter Requirements -Some event types require additional configuration beyond the standard optional filters. These required filters appear in the filter configuration panel when the event type is selected. - -#### Instance State Duration - -This event type requires you to specify the target state and duration threshold. Only one Instance State Duration event is allowed per subscription. +The Instance State Duration event type requires you to specify the target state and duration threshold. Only one Instance State Duration event is allowed per subscription. | Filter | Required | Options | |--------|----------|---------| @@ -83,9 +139,9 @@ This event type requires you to specify the target state and duration threshold. The notification triggers when an instance has been in the specified state for at least the configured duration. If the instance recovers and later re-enters the monitored state, the notification can trigger again after the duration threshold is met. -#### Instance State Flapping +### Instance State Flapping Filter Requirements -This event type requires you to specify the sensitivity of flapping detection. +The Instance State Flapping event type requires you to specify the sensitivity of flapping detection: | Filter | Required | Default | Options | |--------|----------|---------|---------| @@ -97,11 +153,14 @@ The notification triggers when an instance accumulates the specified number of s ### License Field Condition Filters -For customer-related and instance-related events, you can filter notifications based on custom license field (entitlement) values. This allows you to create targeted notifications based on your customers' entitlement data. +You can filter notifications based on your custom license field values. This allows you to create targeted notifications based on your customers' entitlement data. For more information about adding custom license fields, see [Manage Customer License Fields](/vendor/licenses-adding-custom-fields). -**Limitation:** License field conditions are not available for Pending Self-Service Signup, Release, or Channel events. +Filtering by custom license fields is supported for the following event types: +- Customer events (Customer Created, Customer Updated, Customer Archived, Customer Unarchived, Customer License Expiring) +- Instance events (Instance Created, Instance Upgraded, Instance Version Behind, Instance Inactive, Instance State Duration, Instance State Flapping) +- Support Bundle events (Support Bundle Uploaded, Support Bundle Analyzed) -License field conditions use a three-part structure: field, operator, and value. The available operators depend on the field type: +License field conditions have a field, an operator, and a value. The available operators depend on the field type: | Field Type | Available Operators | |------------|-------------------| @@ -111,11 +170,6 @@ License field conditions use a three-part structure: field, operator, and value. When multiple license field conditions are specified, all conditions must match for the notification to trigger (AND logic). -License field conditions are available for the following event types: -- All Customer events (Customer Created, Customer Updated, Customer Archived, Customer Unarchived, Customer License Expiring) -- All Instance events (Instance Created, Instance Upgraded, Instance Version Behind, Instance Inactive, Instance State Duration, Instance State Flapping) -- Support Bundle events (Support Bundle Uploaded, Support Bundle Analyzed) - ## Event Notification Examples The following are example event notifications based on common use cases. @@ -184,4 +238,4 @@ As an Operations Lead, you want to be notified when a customer instance is rapid - Filter - Minimum State Changes: 5 - Filter - Time Window: 30 minutes - Filter - Application: Select your application -- **Delivery Method:** Email to `ops-team@example.com` +- **Delivery Method:** Email to `ops-team@example.com` \ No newline at end of file diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index e5b11e7dd8..f409cffd8d 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -6,17 +6,9 @@ Event Notifications is in Alpha. Features and functionality are subject to chang This topic describes how to view, edit, disable, and delete event notifications in the Replicated Vendor Portal. -## Overview +## View Notification Subscriptions -The Notifications page in the Vendor Portal provides visibility into your notification subscriptions and, optionally, team subscriptions, as well as a complete history of notification events. You can manage your own subscriptions and, if you have the appropriate permissions, view and manage team subscriptions. - -## Viewing Notification Subscriptions - -The Notifications page provides two main views: - -### Overview - -Shows your notification subscriptions. You can optionally include team notifications using the **Show team notifications** checkbox. +For each notification subscription, you can view the delivery channel (email or webhook), the delivery address, the date created, and who created it. If a custom name is set, it appears as the card title. To view notification subscriptions: @@ -25,166 +17,87 @@ To view notification subscriptions: 3. (Optional) Select the **Show team notifications** checkbox to include notifications created by other team members. 4. (Optional) Use the search bar to filter subscriptions by name or event type. - +{/* TODO: Add screenshot of Overview view */} -Each subscription card displays the delivery channel (email or webhook), the delivery address, the date created, and who created it. If a custom name is set, it appears as the card title. - -**Permissions:** -- **Team admins** can manage (edit/delete) any team member's notifications -- **Non-admin users** can view team notifications but cannot modify subscriptions created by others - -### History +## View Notification History and Status Shows all triggered notification events for the selected time period. You can filter the history to show only your notifications or filter by a specific notification, including deleted subscriptions. To view notification history: -1. Navigate to **Notifications** in the Vendor Portal -2. Select the **History** tab +1. In the Vendor Portal, go to **Notifications > History**. 3. Use the filters to narrow results: - Filter by time period - Filter to "My Notifications Only" - Filter to a specific notification (active or deleted) - Filter by delivery status (Delivered, Failed, or Pending) +1. (Optional) Click on an event to view details: + - List of all events that matched this notification's filters + - Timestamp when each event occurred + - Event details (customer, instance, application, etc.) + - Delivery status (Delivered, Failed, Pending) + - For failures: Error message explaining why delivery failed - - -## Viewing Notification Event Details - -Each notification event in the history view can be expanded to show detailed information: +{/* TODO: Add screenshot of History view */} -To view event details: +## Resend a Failed Notification -1. Navigate to **Notifications** > **History** -2. Find the event you want to inspect -3. Click to expand the event row +You can manually resend events with a **Failed** delivery status. -Event details include: -- List of all events that matched this notification's filters -- Timestamp when each event occurred -- Event details (customer, instance, application, etc.) -- Delivery status (Delivered, Failed, Pending) -- For failures: Error message explaining why delivery failed +To resend a failed notification: -This information is helpful for troubleshooting notification delivery issues and understanding which events are triggering your subscriptions. +1. Go to **Notifications** > **History**. +1. Expand the failed event and click **Resend email** or **Resend webhook**. +1. Confirm the resend. -## Editing an Existing Notification +## Edit a Notification -To modify a notification: +You can edit any notifications that you created. Team Admins can also edit notifications created by other team members. -1. Navigate to **Notifications** in the Vendor Portal +Editing a notification does not affect the notification history for past events. -2. Find the notification you want to edit in the list. Select the **Show team notifications** checkbox if the notification was created by another team member. +To edit a notification: -3. Click the **Edit** icon or **Edit** button for that notification +1. In the Vendor Portal, go to **Notifications**. -4. The notification form opens with all current settings populated +1. Next to the notification that you want to modify, click **Edit**. -5. Make your desired changes: +1. Make your changes. For example: - Add or update a custom subscription name to help identify the subscription - Add or remove event types, or modify filters on existing event types to broaden or narrow the scope - Change the delivery method or destination - Check or uncheck the **Enable this notification** checkbox to pause or unpause the notification -6. Click **Save Changes** to update - - - -**Important notes:** -- Editing a notification does not affect past events already sent -- Changes apply immediately to future events -- You can only edit notifications you created, unless you are a team admin with permissions to manage all team notifications +1. Click **Save Changes**. -## Disable a Notification +{/* Add screenshot of Edit notification form */} -To temporarily stop a notification without deleting it: +## Temporarily Disable a Notification -1. Navigate to **Notifications** in the Vendor Portal -2. Find the notification in the list -3. Click the **Edit** button -4. Uncheck the **Enable this notification** checkbox at the bottom of the form -5. Save your changes +When you disable a notification, it stops triggering for new events. The Vendor Portal saves the subscription configuration and any historical event data is still available. -When a notification is disabled: -- It stops triggering for new events -- The subscription configuration is preserved -- Historical event data remains available -- You can re-enable it at any time by editing and checking the **Enable this notification** checkbox +You can re-enable notifications at any time. -## Deleting an Existing Notification +To temporarily disable a notification without deleting its history or configuration: -To permanently remove a notification: +1. In the Vendor Portal, go to **Notifications**. -1. Navigate to **Notifications** in the Vendor Portal +1. Next to the notification that you want to disable, click **Edit**. -2. Find the notification you want to delete in the list +1. Disable the **Enable this notification** checkbox at the bottom of the form. -3. Click the **Delete** icon or **"Delete"** button for that notification +1. Click **Save Changes**. -4. Confirm the deletion in the prompt +## Delete a Notification -5. The notification is permanently removed +You can delete notifications that you created. Team Admins can also delete notifications created by other team members. -**Important notes:** -- Deleting a notification is permanent and cannot be undone -- No further notifications will be sent for this subscription -- Historical event data for the notification is preserved and remains viewable in the History view -- You can only delete notifications you created, unless you're a team admin +Deleting a notification is permanent and cannot be undone. When you delete a notification, historical event data for the notification remains available in the Vendor Portal **Notifications > History** view. -## Viewing Event History for a Specific Notification +To permanently delete a notification: -Each notification maintains a history of when it triggered and what events matched: - -1. Navigate to **Notifications** in the Vendor Portal -2. Find the notification in the list. Select the **Show team notifications** checkbox if the notification was created by another team member. -3. Click the **"View History"** button for that notification - -This filtered view shows only events that matched this specific notification, making it easier to understand the notification's behavior and troubleshoot any issues. - -## Resend a Failed Notification - -If a notification event fails to deliver, you can manually resend it. - -To resend a failed notification: - -1. Navigate to **Notifications** > **History** -1. Find the failed event and expand it -1. Click **Resend email** or **Resend webhook**, depending on the delivery channel -1. Confirm the resend in the confirmation dialog - -:::note -The resend option is only available for events with a Failed delivery status. -::: - -## Troubleshoot Notification Delivery - -### Viewing Delivery Status - -To check if notifications are being delivered successfully: - -1. Navigate to **Notifications** > **History** -2. Look at the **Delivery Status** column for each event: - - **Delivered**: Notification was successfully delivered - - **Failed**: Delivery failed (expand row to see error message) - - **Pending**: Delivery is in progress or queued - -### Common Delivery Issues - -**Email not verified:** -- Check if the email address requires verification -- Look for a verification email in your inbox -- Edit the notification to enter the verification code - -**Filters too restrictive:** -- Review your filter configuration -- Check that events are actually matching your criteria -- Temporarily broaden filters to test +1. Navigate to **Notifications** in the Vendor Portal. -**Webhook endpoint issues:** -- Verify webhook URL is correct and accessible -- Check that your endpoint returns 2xx status codes -- See [Event Notification Webhooks (Alpha)](event-notifications-webhooks) for webhook troubleshooting +1. For the notification that you want to delete, click **Delete**. -**RBAC permissions:** -- Verify you have the necessary permissions to create and manage notifications -- Contact your team admin if you need additional permissions +1. Confirm the deletion in the prompt. diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 74b341720c..1630f895e9 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -1,4 +1,4 @@ -# Configure Event Notification Webhooks (Alpha) +# Configure and Use Webhooks (Alpha) :::note Event Notifications is in Alpha. Features and functionality are subject to change. @@ -8,7 +8,7 @@ This topic describes how to configure and use webhooks for Event Notifications, ## Overview -Webhooks allow you to receive Event Notifications as HTTP POST requests to an endpoint you control. This enables integration with services like Slack, PagerDuty, custom monitoring systems, and other tools that support webhook integrations. +Webhooks allow you to receive notifications as HTTP POST requests to an endpoint you control. This enables integration with services like Slack, PagerDuty, custom monitoring systems, and other tools that support webhook integrations. Event Notifications webhooks include: - JSON payload with event data @@ -19,34 +19,18 @@ Event Notifications webhooks include: - Automatic retries with exponential backoff - Delivery attempt tracking -## Configuring Webhook URLs +## Add Custom HTTP Headers {#custom-headers} -To configure a webhook for Event Notifications: - -1. **Prepare your webhook endpoint:** - - Ensure your endpoint can receive HTTP POST requests - - Endpoint must be publicly accessible (or use a secure tunnel for testing) - - Endpoint should respond with a 2xx status code (200-299) for successful delivery - - Response time should be under 5 seconds - -2. **Create a notification subscription with webhook delivery:** - - Navigate to **Notifications** > **Create Notification** - - Select your event types and configure filters - - Choose **Webhook** as the delivery method - - Enter your webhook URL - - (Optional but recommended) Enter a signing secret for HMAC verification - - (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint. For more information, see [Custom HTTP Headers](#custom-headers). - -3. **Test your webhook:** - - Click **Send test webhook** in the notification form to send a sample payload to your endpoint - - The test result displays the HTTP status code and response time on success, or an error message on failure - - You can also click **View example** to open the payload preview modal and see the exact JSON structure your endpoint receives before testing +You can add custom HTTP headers to webhook subscriptions to authenticate with your receiving endpoint. This is useful when your endpoint requires an API key, bearer token, or other credentials in the request headers. -See [Create Event Notification Subscriptions (Alpha)](event-notifications-create) for detailed instructions on creating subscriptions. +Header values are encrypted at rest and masked in the UI after you save the subscription. To update a saved header value, you must re-enter it. Custom headers are included in both real webhook deliveries and test webhook requests. -## Custom HTTP Headers {#custom-headers} +Custom headers have the following limitations: -You can add custom HTTP headers to webhook subscriptions to authenticate with your receiving endpoint. This is useful when your endpoint requires an API key, bearer token, or other credentials in the request headers. +- Maximum of five headers per subscription +- Header values can be up to 2048 characters +- Duplicate header names are not allowed +- Certain reserved headers (such as `Content-Type` and `Host`) cannot be overridden To add custom headers: @@ -55,16 +39,7 @@ To add custom headers: 1. Enter the header name and value 1. (Optional) Repeat to add additional headers -Custom headers have the following constraints: - -- Maximum of 5 headers per subscription -- Header values can be up to 2048 characters -- Duplicate header names are not allowed -- Certain reserved headers (such as `Content-Type` and `Host`) cannot be overridden - -Header values are encrypted at rest and masked in the UI after you save the subscription. To update a saved header value, you must re-enter it. Custom headers are included in both real webhook deliveries and test webhook requests. - -## Previewing the Webhook Payload Format {#payload-preview} +## Preview the Webhook Payload Format {#payload-preview} When you create or edit a webhook notification and select event types, you can click the **View example** button to open the payload preview modal and see the exact JSON structure your endpoint receives. @@ -74,38 +49,9 @@ The preview shows: Click **Copy payload** to copy the format to your clipboard, which is useful when building your endpoint's request parser. - - -## Testing Webhooks {#test-webhook} - -You can test your webhook endpoint directly from the notification form before activating the subscription. This verifies that your endpoint is reachable, responds correctly, and (if a signing secret is configured) that your signature validation logic works. - -To test a webhook: - -1. Enter a webhook URL in the notification form -2. (Optional) Enter a signing secret -3. Click **Send test webhook** - -The test sends an HTTP POST request to your endpoint with a sample payload that matches the structure of a real event. The test result displays: - -- **On success:** The HTTP status code and response time in milliseconds (for example, "200 OK in 120ms") -- **On failure:** An error message describing the issue (for example, network errors, non-2xx status codes, or timeouts) +{/* Add screenshot of expanded webhook payload format preview */} - - -:::note -Test webhook payloads include a `"test": true` field to distinguish them from real event notifications. The `data` object contains representative sample values (such as "Acme Corp" for customer names) rather than real data from your account. -::: - -### Test Webhook Requirements - -- Your endpoint must be publicly accessible (or reachable through a secure tunnel) -- Your endpoint must respond within 5 seconds with a 2xx status code -- If a signing secret is configured, the test payload is signed with HMAC-SHA256 using the same `X-Replicated-Signature` header as real deliveries -- If custom HTTP headers are configured, they are included in the test request so you can verify your endpoint's authentication logic -- Private and internal IP addresses (localhost, RFC 1918 ranges, link-local, cloud metadata endpoints) are blocked for security - -## Webhook Payload Structure +### Webhook Payload Structure Event Notifications webhooks deliver a JSON payload with the following structure: @@ -143,7 +89,7 @@ The `subscription_name` field is included in the `data` object only when a custo |-------|------|-------------| | `event` | string | Event type identifier (e.g., "customer.created", "instance.upgraded") | | `timestamp` | string | ISO 8601 timestamp when the event occurred | -| `text` | string | Human-readable text description of the event, formatted for easy reading | +| `text` | string | Human-readable text description of the event, formatted for readability in Slack and other chat tools | | `data` | object | Event-specific data containing detailed information about the event | The `data` object contains fields specific to each event type. Common fields include: @@ -155,20 +101,16 @@ The `data` object contains fields specific to each event type. Common fields inc - `subscription_name` - Custom subscription name, if set - Additional fields specific to the event type (customer_id, instance_id, channel_id, etc.) -## Webhook Signing (HMAC-SHA256) +## Verify Webhook Signatures Event Notifications webhooks include an HMAC-SHA256 signature for verification. This allows you to verify that webhook requests are genuinely from Replicated and have not been tampered with. -### How Signing Works - When you configure a webhook with a signing secret: 1. Replicated generates an HMAC-SHA256 signature of the webhook payload using your secret 2. The signature is sent in the `X-Replicated-Signature` HTTP header 3. Your endpoint can verify the signature to ensure authenticity -### Signature Header Format - The `X-Replicated-Signature` header contains the signature in the following format: ``` @@ -180,148 +122,94 @@ Example: X-Replicated-Signature: sha256=5d7f8e9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e ``` -## Verifying Webhook Signatures - -To verify webhook signatures in your endpoint, follow these steps: - -### Step 1: Extract the Signature - -Extract the signature from the `X-Replicated-Signature` header: - -```javascript -const signatureHeader = req.headers['x-replicated-signature']; -const signature = signatureHeader.replace('sha256=', ''); -``` - -### Step 2: Compute the Expected Signature - -Compute the HMAC-SHA256 signature of the raw request body using your signing secret: +To verify webhook signatures in your endpoint: -```javascript -const crypto = require('crypto'); - -const hmac = crypto.createHmac('sha256', signingSecret); -hmac.update(requestBody); // Use the raw request body string -const expectedSignature = hmac.digest('hex'); -``` +1. Extract the signature from the `X-Replicated-Signature` header: -### Step 3: Compare Signatures + ```javascript + const signatureHeader = req.headers['x-replicated-signature']; + const signature = signatureHeader.replace('sha256=', ''); + ``` -Use a constant-time comparison to prevent timing attacks: +1. Compute the HMAC-SHA256 signature of the raw request body using your signing secret: -```javascript -const crypto = require('crypto'); + ```javascript + const crypto = require('crypto'); -function verifySignature(signature, expectedSignature) { - return crypto.timingSafeEqual( - Buffer.from(signature, 'hex'), - Buffer.from(expectedSignature, 'hex') - ); -} + const hmac = crypto.createHmac('sha256', signingSecret); + hmac.update(requestBody); // Use the raw request body string + const expectedSignature = hmac.digest('hex'); + ``` -if (!verifySignature(signature, expectedSignature)) { - // Signature verification failed - reject the request - return res.status(401).send('Invalid signature'); -} +1. Use a constant-time comparison to prevent timing attacks: -// Signature verified - process the webhook -``` + ```javascript + const crypto = require('crypto'); -## Integrating with Slack + function verifySignature(signature, expectedSignature) { + return crypto.timingSafeEqual( + Buffer.from(signature, 'hex'), + Buffer.from(expectedSignature, 'hex') + ); + } -To send Event Notifications to a Slack channel using webhooks: + if (!verifySignature(signature, expectedSignature)) { + // Signature verification failed - reject the request + return res.status(401).send('Invalid signature'); + } -1. **Create a Slack incoming webhook:** - - Go to your Slack workspace settings - - Navigate to **Apps** > **Incoming Webhooks** - - Click **Add to Slack** - - Select the channel where you want to receive notifications - - Copy the webhook URL + // Signature verified - process the webhook + ``` - For detailed instructions, see the [Slack documentation on incoming webhooks](https://api.slack.com/messaging/webhooks). +## Integrate with Slack Using Webhooks -2. **Create an Event Notification subscription:** - - Navigate to **Notifications** > **Create Notification** in the Vendor Portal - - Select your event types and configure filters - - Choose **Webhook** as the delivery method - - Paste your Slack webhook URL - - (Optional) Add a signing secret if you want to verify signatures +For more information about configuring incoming webhooks with Slack, see the [Sending messages using incoming webhooks](https://api.slack.com/messaging/webhooks) in the Slack documentation. -3. **Test the integration:** - - Trigger a test event to verify Slack notifications - - Check your Slack channel for the notification message +To send notifications to a Slack channel using webhooks: -The `text` field in the webhook payload is automatically formatted for readability in Slack and other chat tools. +1. Go to your Slack workspace settings. -## Delivery Retries and Timeouts +1. Navigate to **Apps** > **Incoming Webhooks** and click **Add to Slack**. -Event Notifications automatically retries failed webhook deliveries to ensure reliability. +1. Select the channel where you want to receive notifications. -### Retry Behavior +1. Copy the webhook URL. -- **Initial delivery attempt:** Made immediately when the event occurs -- **Retry policy:** Exponential backoff with up to 8 retry attempts -- **Timeout:** Each delivery attempt times out after 5 seconds -- **Retry schedule:** Approximately 1m, 2m, 4m, 8m, 16m, 32m, 64m, 128m after initial failure +1. Create an Event Notification subscription in the Vendor Portal using your Slack webhook URL. -### Successful Delivery +1. Trigger a test event to verify that the webhook is configured properly. -A webhook delivery is considered successful when your endpoint: -- Responds with an HTTP status code in the 2xx range (200-299) -- Responds within 5 seconds +## Test Webhooks {#test-webhook} -### Failed Delivery +You can test webhooks from the notification form in the Vendor Portal or aginst a local development endpoint. -A webhook delivery is considered failed when: -- Your endpoint responds with a non-2xx status code -- The request times out (exceeds 5 seconds) -- A network error occurs (endpoint unreachable, DNS failure, etc.) - -After all retry attempts are exhausted, the notification is marked as permanently failed and can be viewed in the notification history. An email is also sent to the subscription creator and team admins with details about the failure, including the event type, the last error message, and a link to the delivery history in the Vendor Portal. - -### Auto-Disable - -If a webhook subscription has 10 consecutive permanent failures, it is automatically disabled to prevent continued delivery attempts to an unreachable endpoint. To resume deliveries, verify that your endpoint is reachable and then re-enable the subscription from the **Notifications** page. +Test webhook payloads include a `"test": true` field to distinguish them from real event notifications. The `data` object contains representative sample values (such as "Acme Corp" for customer names) rather than real data from your account. -## Debugging Webhooks {#debugging} +### Test a Webhook from the Vendor Portal -### Viewing Webhook Delivery History +You can test your webhook endpoint from the Vendor Portal **Notifications** page before activating the subscription. This verifies that your endpoint is reachable, responds correctly, and (if a signing secret is configured) that your signature validation logic works. -To debug webhook delivery issues: +To test a webhook: -1. Navigate to **Notifications** > **History** -2. Find the event you're investigating -3. Expand the event row to see: - - Delivery status (Delivered, Failed, Pending) - - Delivery attempts and timestamps - - Error messages for failed attempts - - Response status codes from your endpoint +1. Enter a webhook URL in the notification form +2. (Optional) Enter a signing secret +3. Click **Send test webhook** -### Common Webhook Issues +The test sends an HTTP POST request to your endpoint with a sample payload that matches the structure of a real event. The test result displays: -**Issue: Webhooks not being received** -- Verify webhook URL is correct and publicly accessible -- Check firewall rules and network configuration -- Test endpoint manually with `curl` or Postman -- Review webhook delivery history for error messages +- **On success:** The HTTP status code and response time in milliseconds (for example, "200 OK in 120ms") +- **On failure:** An error message describing the issue (for example, network errors, non-2xx status codes, or timeouts) -**Issue: Signature verification failing** -- Ensure you're using the raw request body (not parsed JSON) -- Verify signing secret matches what you configured in the notification -- Check that you're extracting the signature from the correct header -- Use the verification code examples above as a reference +{/* Add screenshot of test webhook button with success result */} -**Issue: Endpoint timing out** -- Optimize endpoint response time (should be under 5 seconds) -- Process webhooks asynchronously (return 200 immediately, process in background) -- Add logging to identify slow operations +### Test a Webhook Locally -**Issue: Duplicate webhooks received** -- Implement idempotency using the event timestamp and event type -- Store processed event IDs to prevent duplicate processing -- Handle retries gracefully in your application logic +You can test a webhook locally using a development endpoint that is either publicly accessible, or reachable through a secure tunnel. Ensure that your local endpoint meet the -### Testing Webhooks Locally +Note the following: +- If you configured a signing secret, the test payload is signed with HMAC-SHA256 using the same `X-Replicated-Signature` header as real deliveries +- If you configured custom HTTP headers, they are included in the test request so you can verify your endpoint's authentication logic +- Private and internal IP addresses (localhost, RFC 1918 ranges, link-local, cloud metadata endpoints) are blocked for security To test webhooks against a local development endpoint: @@ -335,12 +223,19 @@ To test webhooks against a local development endpoint: https://abc123.ngrok.io/webhook ``` -3. Click **Send test webhook** to send a sample payload to your local endpoint through the tunnel +3. Click **Send test webhook** to send a sample payload to your local endpoint through the tunnel. + +4. Check the ngrok dashboard or your application logs to verify the request was received and processed correctly. + +## About Delivery Retries and Timeouts for Webhooks -4. Check the ngrok dashboard or your application logs to verify the request was received and processed correctly +The Vendor Portal automatically retries failed webhook deliveries to ensure reliability. When a webhook delivery attempt fails, the Vendor Portal makes up to eight retry attempts. Each delivery attempt times out after five seconds. The retry schedule is approximately 1m, 2m, 4m, 8m, 16m, 32m, 64m, 128m after the first failed attempt. + +A webhook delivery is considered failed when: +- The endpoint responds with a non-2xx status code +- The request times out (exceeds 5 seconds) +- A network error occurs (endpoint unreachable, DNS failure, etc.) -## Next Steps +After eight retry attempts, the Vendor Portal marks the notification as permanently failed. The Vendor Portal also sends an email to both the subscription creator and team Admins with details about the failure, including the event type, the last error message, and a link to the delivery history in the Vendor Portal. -- [Create Event Notification Subscriptions (Alpha)](event-notifications-create) - Create webhook subscriptions -- [Manage Event Notification Subscriptions (Alpha)](event-notifications-manage) - View webhook delivery history -- [Event Notifications (Alpha)](event-notifications) - Overview and available event types +If a webhook subscription has 10 consecutive permanent failures, the Vendor Portal automatically disables it. To resume deliveries, verify that your endpoint is reachable and then re-enable the subscription from the **Notifications** page. diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index 01e29afba5..efe16097d9 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -14,69 +14,7 @@ Event types are predefined and organized by category (Instance, Customer, Suppor Events are queued to SQS for reliable processing, and notifications are matched against event filters in real-time. Email notifications are sent through the email service that you configure. Webhook notifications include HMAC signatures for verification. -To get started, review the (Available Event Types)[#available-event-types] below, design event filters based on what matters most to you, and choose your notification delivery method. Then, create your first subscription. For more information, see [Create Event Notification Subscriptions (Alpha)](event-notifications-create). - -## Available Event Types - -Event Notifications (Alpha) supports the following event types, organized by category. You can further refine each event type using filters to match your specific needs. You can also select multiple event types in a single subscription. - -### Instance Events -- **Instance Created**: When a new instance is created -- **Instance Upgraded**: When an instance upgrades to a new release version -- **Instance Version Behind**: When an instance falls behind by a specified number of versions -- **Instance Inactive**: When an instance has not reported in for 24 hours (declared "Inactive"). Air-gapped instances are excluded from this event type. -- **Instance State Duration**: When an instance has been in a specific state (such as Unavailable or Degraded) for a specified duration -- **Instance State Flapping**: When an instance is changing states frequently within a configured time window - -:::note -Instance event notifications use the **Instance Name** if set. Otherwise, they use the Instance ID. -::: - -### Customer Events -- **Customer Created**: When a new customer is created -- **Customer Updated**: When a customer's details or license is updated -- **Customer Archived**: When a customer is archived -- **Customer Unarchived (Restored)**: When a customer is restored from archived state -- **Customer License Expiring**: Time-based warning of an upcoming license expiration -- **Pending Self-Service Signup**: When someone signs up via the self-service portal (if enabled) - -### Support Events -- **Support Bundle Uploaded**: When a support bundle is uploaded -- **Support Bundle Analyzed**: When a support bundle analysis is completed - -### Release Events -- **Release Created**: When a new release is created -- **Release Promoted**: When a release is promoted to a channel -- **Release Demoted (Unpublished)**: When a release is demoted from a channel -- **Release Assets Downloaded**: When a release asset (such as a Helm chart or .tgz bundle) is pulled by a customer - -### Channel Events -- **Channel Created**: When a new channel is created for an application -- **Channel Archived**: When a channel is archived - - -## About RBAC Permissions for Event Notifications {#rbac} - -Event Notifications uses team-scoped RBAC permissions to control access. Your ability to view and manage notifications depends on your role: - -- **Admin**: Full access to all notification features including managing other users' subscriptions. -- **Other roles with write access (Support Engineer, Sales, or custom roles)**: Can create and modify their own notifications. Read-only access to team notifications. -- **Read Only**: Can view all team notifications and their event history, but cannot create notifications. - - For teams that use custom RBAC policies, the following permissions are available: - - `team/notifications/**`: Full access to all notification features including managing other users' subscriptions - - `team/notifications/subscriptions/read`: View all team subscriptions - - `team/notifications/subscriptions/create`: Set up their own alerts - - `team/notifications/subscriptions/update`: Modify their own alerts - - `team/notifications/subscriptions/delete`: Remove their own alerts - - `team/notifications/types/list`: See available event types - - `team/notifications/events/read`: View notification history - - For more information, see [Configure RBAC Policies](team-management-rbac-configuring#configure-a-custom-rbac-policy). - -:::note -When isolating changes to "my" notifications, the logic is based on your user ID being tied to that notification creation record. You may still send to other email addresses not directly associated with your user ID, but those email addresses will need to be verified before the notification will activate. -::: +For more information about how to configure notifications, see [Create Event Notification Subscriptions (Alpha)](event-notifications-create). ## Comparison to Instance Notifications (Classic) From 354eaae052916050b763c349020def600318bfe7 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 3 Mar 2026 15:54:27 -0700 Subject: [PATCH 20/23] docs edits --- docs/vendor/event-notifications-create.mdx | 12 +- docs/vendor/event-notifications-webhooks.mdx | 145 +++++++------------ 2 files changed, 64 insertions(+), 93 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index aa2f4256b7..8ba1e99c87 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -61,10 +61,14 @@ To create an event notification subscription: - Must be publicly accessible (or use a secure tunnel for testing) - Must respond with a 2xx status code (200-299) for successful delivery - Response time must be less than five seconds - 1. (Optional) Enter a signing secret for HMAC signature verification - 1. (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint (for example, `Authorization: Bearer token`). For more information, see [Custom HTTP Headers](event-notifications-webhooks#custom-headers). - 1. After entering a URL, click **View example** to open the webhook payload preview modal and see the exact JSON payload structure your endpoint receives for the selected event types. Click **Copy payload** to copy the format to your clipboard. - 1. Click **Send test webhook** to send a sample payload to your endpoint and verify connectivity. The test result displays the HTTP status code and response time, or an error message with troubleshooting guidance. If you configured a signing secret, the test request is signed with HMAC-SHA256 so you can also verify your signature validation logic. + 1. (Recommended) Enter a signing secret for HMAC signature verification. For more information, see [Verify Webhook Signatures](event-notifications-webhooks#verify-webhook-signatures). + 1. (Optional) Expand **Advanced configuration** to add custom HTTP headers for authenticating with your endpoint (for example, `Authorization: Bearer token`). For more information, see [About Adding Custom HTTP Headers](event-notifications-webhooks#custom-headers). + 1. Click **View example** to open the webhook payload preview modal and see the exact JSON payload structure your endpoint receives for the selected event types. Click **Copy payload** to copy the format to your clipboard. For more information, see [About the Webhook Payload Format](event-notifications-webhooks#payload-preview). + 1. Click **Send test webhook** to send a sample payload to your endpoint and verify connectivity. + + The test sends an HTTP POST request to your endpoint with a sample payload that matches the structure of a real event. Test webhook payloads include a `"test": true` field to distinguish them from real event notifications. The `data` object contains representative sample values (such as "Acme Corp" for customer names) rather than real data from your account. + + The test result displays the HTTP status code and response time, or an error message with troubleshooting guidance. If you configured a signing secret, the test request is signed with HMAC-SHA256 so you can also verify your signature validation logic. diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 1630f895e9..d9d1eaa57e 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -4,22 +4,11 @@ Event Notifications is in Alpha. Features and functionality are subject to change. ::: -This topic describes how to configure and use webhooks for Event Notifications, including webhook payload structure, HMAC signature verification, and integration with services like Slack. - -## Overview +This topic describes how to configure and use webhooks for Event Notifications. Webhooks allow you to receive notifications as HTTP POST requests to an endpoint you control. This enables integration with services like Slack, PagerDuty, custom monitoring systems, and other tools that support webhook integrations. -Event Notifications webhooks include: -- JSON payload with event data -- Event-specific payload format preview with copy support -- Built-in test webhook to verify endpoint connectivity before activating -- Optional custom HTTP headers for webhook authentication -- HMAC-SHA256 signature for verification -- Automatic retries with exponential backoff -- Delivery attempt tracking - -## Add Custom HTTP Headers {#custom-headers} +## About Adding Custom HTTP Headers {#custom-headers} You can add custom HTTP headers to webhook subscriptions to authenticate with your receiving endpoint. This is useful when your endpoint requires an API key, bearer token, or other credentials in the request headers. @@ -32,23 +21,14 @@ Custom headers have the following limitations: - Duplicate header names are not allowed - Certain reserved headers (such as `Content-Type` and `Host`) cannot be overridden -To add custom headers: - -1. In the webhook notification form, expand **Advanced configuration** -1. Click **Add header** -1. Enter the header name and value -1. (Optional) Repeat to add additional headers - -## Preview the Webhook Payload Format {#payload-preview} +## About the Webhook Payload Format {#payload-preview} -When you create or edit a webhook notification and select event types, you can click the **View example** button to open the payload preview modal and see the exact JSON structure your endpoint receives. +When you create or edit a webhook notification and select event types, you can click the **View example** button to open the payload preview modal and see the exact JSON structure your endpoint receives. This is useful when building your endpoint's request parser. The preview shows: - The top-level payload envelope (`event`, `timestamp`, `data`, `text`) - All event-specific fields in the `data` object, with type annotations (string, number, boolean, ISO-8601-timestamp, array, or object) -Click **Copy payload** to copy the format to your clipboard, which is useful when building your endpoint's request parser. - {/* Add screenshot of expanded webhook payload format preview */} ### Webhook Payload Structure @@ -85,42 +65,53 @@ The `subscription_name` field is included in the `data` object only when a custo ### Payload Fields -| Field | Type | Description | -|-------|------|-------------| -| `event` | string | Event type identifier (e.g., "customer.created", "instance.upgraded") | -| `timestamp` | string | ISO 8601 timestamp when the event occurred | -| `text` | string | Human-readable text description of the event, formatted for readability in Slack and other chat tools | -| `data` | object | Event-specific data containing detailed information about the event | - -The `data` object contains fields specific to each event type. Common fields include: -- `app_id` - Application identifier -- `team_id` - Team identifier -- `app_name` - Application name -- `app_slug` - Application slug (URL-safe identifier) -- `event_type` - Event type identifier -- `subscription_name` - Custom subscription name, if set -- Additional fields specific to the event type (customer_id, instance_id, channel_id, etc.) +The following describes the fields in the webhook payload: + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
`event`stringEvent type identifier (e.g., "customer.created", "instance.upgraded")
`timestamp`stringISO 8601 timestamp when the event occurred
`text`stringHuman-readable text description of the event, formatted for readability in Slack and other chat tools
`data`object +

Event-specific data containing detailed information about the event. The `data` object contains fields specific to each event type. Common fields include:

+
    +
  • `app_id` - Application identifier
    • +
  • `team_id` - Team identifier
    • +
  • `app_name` - Application name
    • +
  • `app_slug` - Application slug (URL-safe identifier)
    • +
  • `event_type` - Event type identifier
    • +
  • `subscription_name` - Custom subscription name, if set
    • +
  • Additional fields specific to the event type (customer_id, instance_id, channel_id, etc.)
    • +
+
## Verify Webhook Signatures Event Notifications webhooks include an HMAC-SHA256 signature for verification. This allows you to verify that webhook requests are genuinely from Replicated and have not been tampered with. -When you configure a webhook with a signing secret: - -1. Replicated generates an HMAC-SHA256 signature of the webhook payload using your secret -2. The signature is sent in the `X-Replicated-Signature` HTTP header -3. Your endpoint can verify the signature to ensure authenticity - -The `X-Replicated-Signature` header contains the signature in the following format: - -``` -X-Replicated-Signature: sha256= -``` - -Example: -``` -X-Replicated-Signature: sha256=5d7f8e9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e -``` +When you configure a webhook with a signing secret, Replicated generates an HMAC-SHA256 signature of the webhook payload using your secret. The signature is sent in the `X-Replicated-Signature` HTTP header. The `X-Replicated-Signature` header contains the signature in the following format: `X-Replicated-Signature: sha256=`. For example: +`X-Replicated-Signature: sha256=5d7f8e9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e`. To verify webhook signatures in your endpoint: @@ -168,58 +159,34 @@ For more information about configuring incoming webhooks with Slack, see the [Se To send notifications to a Slack channel using webhooks: 1. Go to your Slack workspace settings. - -1. Navigate to **Apps** > **Incoming Webhooks** and click **Add to Slack**. - +1. Go to **Apps** > **Incoming Webhooks** and click **Add to Slack**. 1. Select the channel where you want to receive notifications. - 1. Copy the webhook URL. - -1. Create an Event Notification subscription in the Vendor Portal using your Slack webhook URL. - +1. Create an Event Notification subscription in the Vendor Portal using your Slack webhook URL. See [Create an Event Notification](/vendor/event-notifications-create#create-an-event-notification). 1. Trigger a test event to verify that the webhook is configured properly. -## Test Webhooks {#test-webhook} - -You can test webhooks from the notification form in the Vendor Portal or aginst a local development endpoint. - -Test webhook payloads include a `"test": true` field to distinguish them from real event notifications. The `data` object contains representative sample values (such as "Acme Corp" for customer names) rather than real data from your account. - -### Test a Webhook from the Vendor Portal - -You can test your webhook endpoint from the Vendor Portal **Notifications** page before activating the subscription. This verifies that your endpoint is reachable, responds correctly, and (if a signing secret is configured) that your signature validation logic works. - -To test a webhook: - -1. Enter a webhook URL in the notification form -2. (Optional) Enter a signing secret -3. Click **Send test webhook** +## Test Webhooks Locally {#test-webhook} -The test sends an HTTP POST request to your endpoint with a sample payload that matches the structure of a real event. The test result displays: - -- **On success:** The HTTP status code and response time in milliseconds (for example, "200 OK in 120ms") -- **On failure:** An error message describing the issue (for example, network errors, non-2xx status codes, or timeouts) - -{/* Add screenshot of test webhook button with success result */} - -### Test a Webhook Locally - -You can test a webhook locally using a development endpoint that is either publicly accessible, or reachable through a secure tunnel. Ensure that your local endpoint meet the +You can test a webhook locally using a development endpoint that is either publicly accessible, or reachable through a secure tunnel. Note the following: - If you configured a signing secret, the test payload is signed with HMAC-SHA256 using the same `X-Replicated-Signature` header as real deliveries - If you configured custom HTTP headers, they are included in the test request so you can verify your endpoint's authentication logic - Private and internal IP addresses (localhost, RFC 1918 ranges, link-local, cloud metadata endpoints) are blocked for security +You can also test webhooks from the Vendor Portal when you create a webhook notification subscription. For more information, see [Create an Event Notification](/vendor/event-notifications-create#create-an-event-notification). + To test webhooks against a local development endpoint: 1. Use a tunnel service like ngrok to expose your local endpoint: - ``` + + ```bash ngrok http 3000 ``` 2. Enter the ngrok URL as your webhook URL in the notification form: - ``` + + ```bash https://abc123.ngrok.io/webhook ``` From 45fb4a0b1b6e34b9e36e0147f8ed2f8076fee8f8 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 3 Mar 2026 15:58:16 -0700 Subject: [PATCH 21/23] minor edits to slack config page --- docs/vendor/team-management-slack-config.mdx | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/docs/vendor/team-management-slack-config.mdx b/docs/vendor/team-management-slack-config.mdx index 0d0ad3ea5e..55b1f59db1 100644 --- a/docs/vendor/team-management-slack-config.mdx +++ b/docs/vendor/team-management-slack-config.mdx @@ -3,10 +3,10 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-abo # Configure a Slack Webhook (Classic) -:::caution Classic System -This Slack webhook configuration is part of the classic Instance Notifications system, which is being replaced by [Event Notifications (Beta)](event-notifications). The new Event Notifications system supports direct webhook delivery to Slack (and other services) without requiring team-level Slack configuration. +:::caution +This Slack webhook configuration is part of Instance Notifications (Classic), which is being replaced by [Event Notifications (Beta)](event-notifications). The new Event Notifications system supports direct webhook delivery to Slack (and other services) without requiring team-level Slack configuration. -For new integrations, we recommend using [Event Notification Webhooks (Beta)](event-notifications-webhooks) instead. +For new integrations, Replicated recommends using [Event Notification Webhooks (Beta)](event-notifications-webhooks) instead. ::: As a vendor, anyone on your team can set up Slack notifications, which are sent to a shared Slack channel. Notifications give your team visibility into customer instance statuses and changes. @@ -38,12 +38,3 @@ To configure the Slack webhook: 1. From the **[Team Vendor Portal](https://vendor.replicated.com/team/members)** page, click **Slack Notifications**. 1. On the **Slack Notifications Setup** page, paste the Slack webhook URL. Click **Save**. - -## Next Steps - -**For classic Instance Notifications:** -- [Configure Instance Notifications (Classic)](instance-notifications-config) - Configure Slack notifications for customer instances - -**For new Event Notifications:** -- [Event Notification Webhooks (Beta)](event-notifications-webhooks) - Send notifications directly to Slack using webhooks (no team-level configuration required) -- [Create Event Notification Subscriptions (Beta)](event-notifications-create) - Set up notification subscriptions with the new system From cd90e608581bdbd985481e401e5334e5f2698478 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 4 Mar 2026 08:50:10 -0700 Subject: [PATCH 22/23] remove beta labels --- docs/vendor/instance-notifications-config.mdx | 6 ++---- docs/vendor/team-management-slack-config.mdx | 4 ++-- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/vendor/instance-notifications-config.mdx b/docs/vendor/instance-notifications-config.mdx index e418ff7a56..aabf88ce4d 100644 --- a/docs/vendor/instance-notifications-config.mdx +++ b/docs/vendor/instance-notifications-config.mdx @@ -3,10 +3,8 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-abo # Configure Instance Notifications (Classic) -:::caution Classic System -This notification system is being replaced by [Event Notifications (Alpha)](event-notifications), which offers more event types, better filtering, and improved delivery options. While this classic system continues to work, we recommend exploring Event Notifications for new notification configurations. - -For a comparison of features, see [Comparison: Classic vs. Event Notifications](event-notifications#comparison-classic-instance-notifications-vs-event-notifications-alpha). +:::caution +The Instance Notifications (Classic) system is replaced by [Event Notifications (Alpha)](event-notifications), which offers more event types, better filtering, and improved delivery options. While Instance Notifications (Classic) is still supported, Replicated recommends using Event Notifications (Alpha). For more information about how to configure event notifications, see [About Event Notifications (Alpha)](event-notifications). ::: diff --git a/docs/vendor/team-management-slack-config.mdx b/docs/vendor/team-management-slack-config.mdx index 55b1f59db1..7acef3d04b 100644 --- a/docs/vendor/team-management-slack-config.mdx +++ b/docs/vendor/team-management-slack-config.mdx @@ -4,9 +4,9 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-abo # Configure a Slack Webhook (Classic) :::caution -This Slack webhook configuration is part of Instance Notifications (Classic), which is being replaced by [Event Notifications (Beta)](event-notifications). The new Event Notifications system supports direct webhook delivery to Slack (and other services) without requiring team-level Slack configuration. +This Slack webhook configuration is part of Instance Notifications (Classic), which is being replaced by [Event Notifications (Alpha)](event-notifications). The new Event Notifications system supports direct webhook delivery to Slack (and other services) without requiring team-level Slack configuration. -For new integrations, Replicated recommends using [Event Notification Webhooks (Beta)](event-notifications-webhooks) instead. +For new integrations, Replicated recommends using [Event Notification Webhooks (Alpha)](event-notifications-webhooks) instead. ::: As a vendor, anyone on your team can set up Slack notifications, which are sent to a shared Slack channel. Notifications give your team visibility into customer instance statuses and changes. From 02ce9e04115ce683a0c31984b97747f90ef86dab Mon Sep 17 00:00:00 2001 From: Amber Alston Date: Wed, 4 Mar 2026 11:28:51 -0700 Subject: [PATCH 23/23] Modify event notification filter states Updated for new multi-select feature on this alert, which is more realistic example --- docs/vendor/event-notifications-create.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 8ba1e99c87..c35d0b6c95 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -227,7 +227,7 @@ As a Support Engineer, you want to be notified when a customer instance has been - **Event Type:** Instance State Duration - **Configuration:** - - Filter - State: "Unavailable" + - Filter - State: Select "Unavailable", "Missing", and "Degraded" - Filter - Duration: "1 hour" - Filter - Application: Select your production application - Filter - License Type: "Paid" @@ -242,4 +242,4 @@ As an Operations Lead, you want to be notified when a customer instance is rapid - Filter - Minimum State Changes: 5 - Filter - Time Window: 30 minutes - Filter - Application: Select your application -- **Delivery Method:** Email to `ops-team@example.com` \ No newline at end of file +- **Delivery Method:** Email to `ops-team@example.com`