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_. diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx new file mode 100644 index 0000000000..c35d0b6c95 --- /dev/null +++ b/docs/vendor/event-notifications-create.mdx @@ -0,0 +1,245 @@ +# Create Event Notification Subscriptions (Alpha) + +:::note +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. + +## RBAC Requirements + +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. In the Vendor Portal, go to **Notifications**. + +1. Click **Create Notification**. + +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. + + 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. 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. + ::: + + + +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. + ::: + +1. Click **Done**. + + + +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. 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. (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. + + + +1. Click **Create Notification**. + +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. + +## 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 + + +## 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: + +- **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. + +If a filter contains multiple selected values, the event must match _any_ of the selected values (OR logic) to satisfy the filter. + +### Instance State Duration Filter Requirements + +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 | +|--------|----------|---------| +| 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 Filter Requirements + +The Instance State Flapping 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 + +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). + +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 have a field, an operator, and a 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). + +## 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) + +### Support Engineer: Unhealthy Instance Alert + +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: Select "Unavailable", "Missing", and "Degraded" + - 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 + +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 new file mode 100644 index 0000000000..f409cffd8d --- /dev/null +++ b/docs/vendor/event-notifications-manage.mdx @@ -0,0 +1,103 @@ +# Manage Event Notification Subscriptions (Alpha) + +:::note +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. + +## View Notification Subscriptions + +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: + +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. + +{/* TODO: Add screenshot of Overview view */} + +## 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. 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 + +{/* TODO: Add screenshot of History view */} + +## Resend a Failed Notification + +You can manually resend events with a **Failed** delivery status. + +To resend a failed notification: + +1. Go to **Notifications** > **History**. +1. Expand the failed event and click **Resend email** or **Resend webhook**. +1. Confirm the resend. + +## Edit a Notification + +You can edit any notifications that you created. Team Admins can also edit notifications created by other team members. + +Editing a notification does not affect the notification history for past events. + +To edit a notification: + +1. In the Vendor Portal, go to **Notifications**. + +1. Next to the notification that you want to modify, click **Edit**. + +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 + +1. Click **Save Changes**. + +{/* Add screenshot of Edit notification form */} + +## Temporarily Disable a Notification + +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. + +You can re-enable notifications at any time. + +To temporarily disable a notification without deleting its history or configuration: + +1. In the Vendor Portal, go to **Notifications**. + +1. Next to the notification that you want to disable, click **Edit**. + +1. Disable the **Enable this notification** checkbox at the bottom of the form. + +1. Click **Save Changes**. + +## Delete a Notification + +You can delete notifications that you created. Team Admins can also delete notifications created by other team members. + +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. + +To permanently delete a notification: + +1. Navigate to **Notifications** in the Vendor Portal. + +1. For the notification that you want to delete, click **Delete**. + +1. Confirm the deletion in the prompt. diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx new file mode 100644 index 0000000000..d9d1eaa57e --- /dev/null +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -0,0 +1,208 @@ +# Configure and Use Webhooks (Alpha) + +:::note +Event Notifications is in Alpha. Features and functionality are subject to change. +::: + +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. + +## 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. + +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 headers have the following limitations: + +- 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 + +## 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. 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) + +{/* Add screenshot of expanded webhook payload format preview */} + +### 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", + "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 + +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, 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: + +1. Extract the signature from the `X-Replicated-Signature` header: + + ```javascript + const signatureHeader = req.headers['x-replicated-signature']; + const signature = signatureHeader.replace('sha256=', ''); + ``` + +1. 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'); + ``` + +1. 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 + ``` + +## Integrate with Slack Using Webhooks + +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. + +To send notifications to a Slack channel using webhooks: + +1. Go to your Slack workspace settings. +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. 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 Locally {#test-webhook} + +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 + ``` + +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 + +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.) + +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. + +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 new file mode 100644 index 0000000000..efe16097d9 --- /dev/null +++ b/docs/vendor/event-notifications.mdx @@ -0,0 +1,43 @@ +# About Event Notifications (Alpha) + +:::note +Event Notifications is in Alpha. Features and functionality are subject to change. +::: + +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 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 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 through the email service that you configure. Webhook notifications include HMAC signatures for verification. + +For more information about how to configure notifications, see [Create Event Notification Subscriptions (Alpha)](event-notifications-create). + +## Comparison to Instance Notifications (Classic) + +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. + +You can use Event Notifications (Alpha) concurrently with Instance Notifications (Classic) while you evaluate and transition. + +The following table compares the functionality offered by Instance Notifications (Classic) and Event Notifications (Alpha): + +| 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. diff --git a/docs/vendor/instance-notifications-config.mdx b/docs/vendor/instance-notifications-config.mdx index 25057650c6..aabf88ce4d 100644 --- a/docs/vendor/instance-notifications-config.mdx +++ b/docs/vendor/instance-notifications-config.mdx @@ -1,7 +1,11 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-about.mdx" -# Configure Instance Notifications (Beta) +# Configure Instance Notifications (Classic) + +:::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). +::: @@ -56,4 +60,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 (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 diff --git a/docs/vendor/team-management-rbac-resource-names.md b/docs/vendor/team-management-rbac-resource-names.md index d161f30237..b46c701962 100644 --- a/docs/vendor/team-management-rbac-resource-names.md +++ b/docs/vendor/team-management-rbac-resource-names.md @@ -482,11 +482,15 @@ 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/\*\* + +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/policy/read diff --git a/docs/vendor/team-management-slack-config.mdx b/docs/vendor/team-management-slack-config.mdx index 3d7bd7939e..7acef3d04b 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 +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 (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. @@ -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. @@ -32,7 +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 Step - -[Configure Slack notifications for customer instances](instance-notifications-config). diff --git a/sidebars.js b/sidebars.js index 7d9917e0de..346f04213d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -180,12 +180,22 @@ 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", "vendor/instance-insights-details", + { + type: "category", + label: "Event Notifications (Alpha)", + items: [ + "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", ], },