diff --git a/.github/workflows/vale-pr-review.yml b/.github/workflows/vale-pr-review.yml index 01d6d6c48a..efff99ca0b 100644 --- a/.github/workflows/vale-pr-review.yml +++ b/.github/workflows/vale-pr-review.yml @@ -26,6 +26,7 @@ jobs: files_ignore: | docs/reference/kots-cli-* docs/reference/replicated-cli-* + docs/reference/notifications-* docs/release-notes/rn-* separator: " " diff --git a/.vale.ini b/.vale.ini index 260aae7e88..51ff9b2bd6 100644 --- a/.vale.ini +++ b/.vale.ini @@ -29,3 +29,7 @@ BasedOnStyles = # Don't lint release notes [docs/release-notes/rn-*] BasedOnStyles = + +# Don't lint Event Notifications reference topics +[docs/reference/notifications-*] +BasedOnStyles = diff --git a/docs/reference/notifications-events-filters.md b/docs/reference/notifications-events-filters.md new file mode 100644 index 0000000000..922d76f99e --- /dev/null +++ b/docs/reference/notifications-events-filters.md @@ -0,0 +1,181 @@ +# Event types and filters (Beta) + +For more information about the Event Notifications (Beta) feature, see [About event notifications (Beta)](/vendor/event-notifications). + +This topic lists the types of events supported for the Event Notifications (Beta) feature. + +## Channel events + +### Channel Created + +When a new channel is created for an application. + +### Channel Archived + +When a channel is archived. + +## 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). + +## Instance events + +### Instance Created + +When a new instance sends its first check-in. + +### Instance Ready + +When a new instance's application status is Ready for the first time. + +### Instance Upgrade Started + +When an instance begins upgrading to a new release version. This event fires when the Vendor Portal receives the first telemetry with a new release version, whether or not the application status is Ready. + +### Instance Upgrade Completed + +When an instance's application status is Ready after upgrading 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 checked-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. + +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 + +When an instance is changing states frequently within a configured time window. + +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. + +### Custom Metric Threshold Reached + +When a custom metric value reported by an instance meets a configured threshold condition. + +:::note +Instance event notifications use the **Instance Name** if set. Otherwise, they use the Instance ID. +::: + +The Custom Metric Threshold Reached event type requires a metric name, comparison operator, and notification frequency. You can include only one Custom Metric Threshold Reached event per subscription. + +The following table describes each of the filters for the Custom Metric Threshold Reached event type: + +| Filter | Required | Description | +|--------|----------|-------------| +| Metric Name | Yes | Select from previously reported custom metrics or enter a metric name manually | +| Operator | Yes | Comparison operator. The operators available depend on the metric type. For more information, see [Available operators](#available-operators). | +| Threshold Value | Conditional | Required for all operators except `is_true`, `is_false`, `exists`, and `not_exists` | +| Frequency | Yes | Controls how often you receive the notification. For more information, see [Frequency options](#frequency-options). | + +#### Available operators + +The available operators depend on the type of metric value: + +| Metric Type | Available Operators | +|-------------|-------------------| +| Number | greater than, greater than or equal, less than, less than or equal, equals, does not equal, exists, does not exist | +| Boolean | is true, is false, equals, does not equal, exists, does not exist | +| String | contains, starts with, ends with, equals, does not equal, exists, does not exist | + +#### Frequency options + +The following frequency options control how often the notification triggers: + +| Frequency | Behavior | +|-----------|----------| +| Send Once | Notifies the first time the metric meets the threshold. Does not notify again until the condition clears and the metric meets the threshold again. | +| When Changed | Notifies when the metric meets the threshold and its value has changed since the last notification. | +| Each Time | Notifies every time a metric report meets the threshold condition. | + +## 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 {#release-assets-downloaded} + +When a customer pulls a release asset (Helm chart, Embedded Cluster bundle, or proxy registry image). Fires one time per individual asset pull. Includes whether this is the customer's first ever software pull, which is useful for revenue recognition tracking. + +The following table describes the available filters for the Release Assets Downloaded event type: + +| Filter | Required | Options | +|--------|----------|---------| +| Application | No | Any application in your account | +| Channel | No | Any channel for the selected application | +| Customer | No | Any customer for the selected application | +| License Type | No | Paid, Trial, Community, Development | +| Asset Type | No | Helm Chart, Embedded Cluster Bundle, Proxy Registry Image | +| Pull Type | No | First Pull Only, Any Pull | + +The **Pull Type** filter controls whether the notification fires on every pull or only the first time a customer pulls any software asset: + +- **First Pull Only**: The notification fires only when a customer pulls a release asset for the first time, across all asset types. Use this to track the revenue recognition milestone when a customer first retrieves your software. +- **Any Pull** (default): The notification fires on every pull. This is equivalent to leaving the filter unset, and all existing subscriptions behave this way. + +:::note +First pull tracking is forward-only. Customers who pulled software before this feature shipped will have `is_first_customer_pull: false` on all subsequent pulls. +::: + +## Support events + +### Support Bundle Uploaded + +When a support bundle is uploaded. + +### Support Bundle Analyzed + +When a support bundle analysis is completed. diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 27d7f67721..56491f3128 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -1,23 +1,6 @@ # Create event notification subscriptions (Beta) -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). +This topic describes how to create event notification subscriptions in the Replicated Vendor Portal. For more information about the Event Notifications (Beta) feature, see [About event notifications (Beta)](/vendor/event-notifications). ## Create an event notification @@ -31,7 +14,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. For more information, see [Event Types](#event-types) on this page. +1. Select one or more event types to include in the subscription. For more information, see [Event types and filters (Beta)](/reference/notifications-events-filters). :::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. @@ -39,11 +22,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, see [Event Filter Logic and Requirements](#filter-logic) on this page. - - :::note - To configure a channel filter, you must first select an application. - ::: +1. (Optional) For each of the events that you selected, click the filter icon to configure event filters. For more information about how the Vendor Portal uses filters to trigger notifications, see [Events and filters](/vendor/event-notifications#events-and-filters) in _About event notifications (Beta)_. 1. Click **Done**. @@ -57,9 +36,9 @@ 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. (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. (Recommended) Enter a signing secret for HMAC signature verification. For more information, see [Verify webhook signatures](event-notifications-webhooks#verify-webhook-signatures) in _Configure and test webhooks (Beta)_. + 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) in _Configure and test webhooks (Beta)_. + 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. 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. @@ -72,162 +51,6 @@ 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. -## Event types - -Event Notifications (Beta) 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 sends its first check-in -- **Instance Ready**: When a new instance's application status is Ready for the first time -- **Instance Upgrade Started**: When an instance begins upgrading to a new release version. This event fires when the Vendor Portal receives the first telemetry with a new release version, whether or not the application status is Ready. -- **Instance Upgrade Completed**: When an instance's application status is Ready after upgrading 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 checked-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 -- **Custom Metric Threshold Reached**: When a custom metric value reported by an instance meets a configured threshold condition - -:::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 customer pulls a release asset (Helm chart, Embedded Cluster bundle, or proxy registry image). Fires one time per individual asset pull. Includes whether this is the customer's first ever software pull, which is useful for revenue recognition tracking. - -### 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. - -### Custom metric threshold reached filter requirements - -The Custom Metric Threshold Reached event type requires a metric name, comparison operator, and notification frequency. You can include only one Custom Metric Threshold Reached event per subscription. - -The following table describes each of the filters for the Custom Metric Threshold Reached event type: - -| Filter | Required | Description | -|--------|----------|-------------| -| Metric Name | Yes | Select from previously reported custom metrics or enter a metric name manually | -| Operator | Yes | Comparison operator. The operators available depend on the metric type. For more information, see [Available Operators](#available-operators). | -| Threshold Value | Conditional | Required for all operators except `is_true`, `is_false`, `exists`, and `not_exists` | -| Frequency | Yes | Controls how often you receive the notification. For more information, see [Frequency Options](#frequency-options). | - -#### Available operators - -The available operators depend on the type of metric value: - -| Metric Type | Available Operators | -|-------------|-------------------| -| Number | greater than, greater than or equal, less than, less than or equal, equals, does not equal, exists, does not exist | -| Boolean | is true, is false, equals, does not equal, exists, does not exist | -| String | contains, starts with, ends with, equals, does not equal, exists, does not exist | - -#### Frequency options - -The following frequency options control how often the notification triggers: - -| Frequency | Behavior | -|-----------|----------| -| Send Once | Notifies the first time the metric meets the threshold. Does not notify again until the condition clears and the metric meets the threshold again. | -| When Changed | Notifies when the metric meets the threshold and its value has changed since the last notification. | -| Each Time | Notifies every time a metric report meets the threshold condition. | - -### Release assets downloaded filter requirements - -The following table describes the available filters for the Release Assets Downloaded event type: - -| Filter | Required | Options | -|--------|----------|---------| -| Application | No | Any application in your account | -| Channel | No | Any channel for the selected application | -| Customer | No | Any customer for the selected application | -| License Type | No | Paid, Trial, Community, `dev` | -| Asset Type | No | Helm Chart, Embedded Cluster Bundle, Proxy Registry Image | -| Pull Type | No | First Pull Only, Any Pull | - -The **Pull Type** filter controls whether the notification fires on every pull or only the first time a customer pulls any software asset: - -- **First Pull Only**: The notification fires only when a customer pulls a release asset for the first time, across all asset types. Use this to track the revenue recognition milestone when a customer first retrieves your software. -- **Any Pull** (default): The notification fires on every pull. This is equivalent to leaving the filter unset, and all existing subscriptions behave this way. - -:::note -First pull tracking is forward-only. Customers who pulled software before this feature shipped will have `is_first_customer_pull: false` on all subsequent pulls. -::: - -### 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 Ready, Instance Upgrade Started, Instance Upgrade Completed, 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. diff --git a/docs/vendor/event-notifications-manage.mdx b/docs/vendor/event-notifications-manage.mdx index 533c16d039..ad8a9b08e7 100644 --- a/docs/vendor/event-notifications-manage.mdx +++ b/docs/vendor/event-notifications-manage.mdx @@ -1,6 +1,6 @@ # Manage event notification subscriptions (Beta) -This topic describes how to view, edit, disable, and delete event notifications in the Replicated Vendor Portal. +This topic describes how to view, edit, disable, and delete event notifications in the Replicated Vendor Portal. For more information about the Event Notifications (Beta) feature, see [About event notifications (Beta)](/vendor/event-notifications). ## View notification subscriptions diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index a70240f2be..7caf72ca1a 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -1,132 +1,51 @@ -# Configure and use webhooks (Beta) +# Configure and test webhooks (Beta) -This topic describes how to configure and use webhooks for Event Notifications. +This topic describes how to configure and test webhooks for event notifications. For information about how to create a notification using a webhook URL, see [Create event notification subscriptions (Beta)](/vendor/event-notifications-create). 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} +## Integrate with Slack using webhooks -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 send notifications to Slack, enable incoming webhooks on a new or existing Slack app, and then use the generated webhook URL as your subscription endpoint. For more information about incoming webhooks, see [Sending messages using incoming webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks) in the Slack documentation. -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. +To send notifications to a Slack channel using webhooks: -Custom headers have the following limitations: +1. Create a Slack app for your workspace, or use an existing one. To use the Slack API to create an app, go to `https://api.slack.com/apps/new` in a browser. +1. In your Slack app settings, enable **Incoming Webhooks**. +1. Click **Add New Webhook to Workspace** and select the channel where you want to receive notifications. + :::note + You can send each notification to one Slack channel. To generate additional webhooks URLs to use for different event notifications, click **Add New Webhook to Workspace** again and select the target channel. + ::: +1. Copy the generated 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. -- 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 +## 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. 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). + +When 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: + +1. Use a tunnel service like [ngrok](https://ngrok.com/docs/start) 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 + ``` -## 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.upgrade_started")
`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.). For event-specific field reference, see Event-specific fields on this page.
    • -
-
- -## Event-specific fields {#event-specific-fields} - -The `data` object in the webhook payload contains fields that vary by event type. The following describes the additional fields for event types that have notable fields beyond the common set. - -### Release asset downloaded - -The `release.asset_downloaded` event fires each time a customer pulls a release asset (Helm chart, Embedded Cluster bundle, or proxy registry image). - -| Field | Type | Description | -|-------|------|-------------| -| `customer_id` | string | Customer identifier | -| `customer_name` | string | Customer display name | -| `channel_id` | string | Channel identifier | -| `channel_name` | string | Channel name | -| `license_type` | string | License type: `paid`, `trial`, `dev`, or `community` | -| `asset_type` | string | Type of asset pulled: `helm_chart`, `embedded_cluster_bundle`, or `proxy_image` | -| `asset_name` | string | Name of the asset (chart name, app slug, or full proxy path) | -| `asset_version` | string | Version or tag of the asset | -| `service_account_name` | string | Enterprise Portal service account name, if a service account made the pull. Empty for direct license pulls. | -| `is_first_customer_pull` | boolean | `true` if this is the first software pull by this customer across all asset types; `false` for all subsequent pulls. Forward-only: customers who pulled software before this feature shipped will always have `false`. | -| `downloaded_at` | string | Timestamp (International Organization for Standardization (ISO) 8601 format) of when the pull occurred | - -:::note -The `is_first_customer_pull` field is useful for revenue recognition workflows. Use the **Pull Type: First Pull Only** filter on your subscription to receive notifications only for first pulls. -::: +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. ## Verify webhook signatures @@ -174,51 +93,6 @@ To verify webhook signatures in your endpoint: // Signature verified - process the webhook ``` -## Integrate with Slack using webhooks - -To send notifications to Slack, enable incoming webhooks on a new or existing Slack app, and then use the generated webhook URL as your subscription endpoint. For more information about incoming webhooks, see [Sending messages using incoming webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks) in the Slack documentation. - -To send notifications to a Slack channel using webhooks: - -1. Create a Slack app for your workspace, or use an existing one. To use the Slack API to create an app, go to `https://api.slack.com/apps/new` in a browser. -1. In your Slack app settings, enable **Incoming Webhooks**. -1. Click **Add New Webhook to Workspace** and select the channel where you want to receive notifications. - :::note - You can send each notification to one Slack channel. To generate additional webhooks URLs to use for different event notifications, click **Add New Webhook to Workspace** again and select the target channel. - ::: -1. Copy the generated 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. @@ -231,3 +105,16 @@ A webhook delivery is considered failed when: 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. + +## 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 diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index 22c0e7e710..8955c90700 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -1,18 +1,78 @@ # About event notifications (Beta) -This topic provides an introduction to the Event Notifications (Beta) feature, which allows you to set up notifications for key events from the Vendor Portal. +This topic provides an overview of the Event Notifications (Beta) 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. +You can define and subscribe to notifications in the Vendor Portal to receive alerts when specific events occur. Built-in event types and filters allow you to create highly-targeted notifications for the events that matter most to your workflow. For example, Customer Success Managers could get an email notification when a key customer uploads a support bundle. Or, Support Engineers could get a Slack notification when a customer instance has been in an unhealthy state for an extended period. -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). +The Vendor Portal queues events to Amazon Simple Queue Service (SQS) for reliable processing, and matches notifications against your custom event filters in real time. You can receive notifications through email or webhook. For information about how to create and subscribe to event notifications, see [Create event notification subscriptions (Beta)](event-notifications-create). -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. +## Events and filters -For more information about how to configure notifications, see [Create Event Notification Subscriptions (Beta)](event-notifications-create). +This section describes the types of events and filters that are available for creating notifications. It also describes the logic that the Vendor Portal uses to determine if a given event satisfies the conditions to send a notification. -## Comparison to instance notifications (classic) +### Supported event types + +You can create notifications for various types of events, including events related to application instances, customers, support bundles, releases, and channels. For example, you can get a notification when an instance reaches a Ready state in the customer environment, when the customer uploads a new support bundle, or when a customer license is expiring soon. + +For the full list of available event types and event-specific filters, see [Event types and filters (Beta)](/reference/notifications-events-filters). + +### Multi-event notifications + +Each notification can have one or more events. For notifications that include multiple events, the Vendor Portal evaluates each event independently against its filters. If any event matches its filters, then the Vendor Portal triggers a notification. + +For example, if you create a notification with both the **Release Created** and **Release Promoted** events and no additional filters, then the Vendor Portal sends a notification any time a release is created _or_ promoted. + +### Event filters + +You can configure a unique set of filters for each event that you add to a notification. An event must match _all_ its filters to trigger the notification (AND logic). + +The filters available depend on the event type. All events support filtering by application name. Other common filters that apply to most event types include the channel, customer name, and license type. For more information, see [Event types and filters (Beta)](/reference/notifications-events-filters). + +### Filters with multiple values + +If a single filter has multiple values, then the event must match _any_ of the selected values (OR logic) to satisfy the filter. + +For example, if you select both **Paid** and **Community** for the **License type** filter, then the filter is satisfied if the license type is either Paid or Community. + +### Custom license field filters + +When you specify multiple custom license field filters, all conditions must match for the notification to trigger (AND logic). For example, if you add filters for `seats > 99` and `tier == Enterprise`, then the value of the `seats` custom license field must be greater than `99` _and_ the value of the `tier` custom license field must be `Enterprise` to trigger a notification. + +The Vendor Portal supports filtering by custom license fields for the following event types: +- Customer events (Customer Created, Customer Updated, Customer Archived, Customer Unarchived, Customer License Expiring) +- Instance events (Instance Created, Instance Ready, Instance Upgrade Started, Instance Upgrade Completed, Instance Version Behind, Instance Inactive, Instance State Duration, Instance State Flapping) +- Support Bundle events (Support Bundle Uploaded, Support Bundle Analyzed) + +For information about how to create custom license fields, see [Manage custom license fields](/vendor/licenses-adding-custom-fields#manage-custom-license-fields) in _Create and manage customers_. + +## RBAC requirements + +Roles with write access (Admin, Support Engineer, Sales, or custom roles) can create and manage their own notifications. They can also view notifications created by others. + +Only Admins can create and 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). + +## Limitations + +Event Notifications (Beta) has the following limitations: + +- 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. Because release assets might be shared across many of your release versions, the Vendor Portal records the event at the chart/image level and does not associate the event with a specific release version. If you find this alert too noisy, reach out to us to further discuss your specific use case. + +## Comparison to instance notifications (Classic) Event Notifications (Beta) 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 delivery routing, notification history tracking, and better access control. @@ -30,9 +90,3 @@ The following table compares the functionality offered by Instance Notifications | **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 - -- 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/team-management-slack-config.mdx b/docs/vendor/team-management-slack-config.mdx index dae34db2b2..dcd3b2f1c3 100644 --- a/docs/vendor/team-management-slack-config.mdx +++ b/docs/vendor/team-management-slack-config.mdx @@ -6,7 +6,7 @@ import NotificationsAbout from "../partials/instance-insights/_notifications-abo :::caution This Slack webhook configuration is part of Instance Notifications (Classic). [Event Notifications (Beta)](event-notifications) replaces this system. 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 [Configure and test 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. diff --git a/sidebars.js b/sidebars.js index d3e43d3425..d21d0c3939 100644 --- a/sidebars.js +++ b/sidebars.js @@ -192,8 +192,9 @@ const sidebars = { items: [ "vendor/event-notifications", "vendor/event-notifications-create", - "vendor/event-notifications-manage", + "reference/notifications-events-filters", "vendor/event-notifications-webhooks", + "vendor/event-notifications-manage", ], }, "vendor/instance-notifications-config",