From 969f0093619aa6fd373a61fa06bd4646d3ae2fb1 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 19 Mar 2026 10:37:49 -0600 Subject: [PATCH 1/6] wip create event notifications reference docs --- docs/reference/event-types.md | 195 +++++++++++++++++++++ docs/vendor/event-notifications-create.mdx | 138 +-------------- sidebars.js | 1 + 3 files changed, 198 insertions(+), 136 deletions(-) create mode 100644 docs/reference/event-types.md diff --git a/docs/reference/event-types.md b/docs/reference/event-types.md new file mode 100644 index 0000000000..1d49fa5cdc --- /dev/null +++ b/docs/reference/event-types.md @@ -0,0 +1,195 @@ +# Event types (Beta) + +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. + +## 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. + +## License field operators + +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). + + +## 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. + +### 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 + +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. | + +## 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. diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 2faae7d16c..05708608fc 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -31,7 +31,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 (Beta)](/reference/event-types). :::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,7 +39,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. +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](/reference/event-types#event-filter-logic-and-requirements). :::note To configure a channel filter, you must first select an application. @@ -72,140 +72,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 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. - -### 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. | - -### 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/sidebars.js b/sidebars.js index d3e43d3425..700dde2262 100644 --- a/sidebars.js +++ b/sidebars.js @@ -192,6 +192,7 @@ const sidebars = { items: [ "vendor/event-notifications", "vendor/event-notifications-create", + "reference/event-types", "vendor/event-notifications-manage", "vendor/event-notifications-webhooks", ], From 996f321f0a44dbbacb8f4df9656f6cebe46c42b0 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 19 Mar 2026 14:17:13 -0600 Subject: [PATCH 2/6] wip reorg notifications reference docs --- docs/reference/event-types.md | 114 +++++----- docs/reference/webhooks.md | 133 ++++++++++++ docs/vendor/event-notifications-create.mdx | 21 +- docs/vendor/event-notifications-webhooks.mdx | 211 +++++-------------- docs/vendor/event-notifications.mdx | 76 ++++++- sidebars.js | 3 +- 6 files changed, 302 insertions(+), 256 deletions(-) create mode 100644 docs/reference/webhooks.md diff --git a/docs/reference/event-types.md b/docs/reference/event-types.md index 1d49fa5cdc..0c435b44bc 100644 --- a/docs/reference/event-types.md +++ b/docs/reference/event-types.md @@ -1,40 +1,42 @@ -# Event types (Beta) +# Event types and filters (Beta) -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. +This topic lists the types of events supported for the Event Notifications (Beta) feature. For more information about event notifications, see [About event notifications (Beta)](/vendor/event-notifications). -## Filter logic +## Channel events -Each event type that you select in a notification subscription has its own set of filters. +### Channel Created -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. +When a new channel is created for an application. -The following describes the filter logic used for each event: +### Channel Archived -- **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. +When a channel is archived. -If a filter contains multiple selected values, the event must match _any_ of the selected values (OR logic) to satisfy the filter. +## Customer events -## License field operators +### Customer Created -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). +When a new customer is created. -Filtering by custom license fields is supported for the following event types: +### Customer Updated -- 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) +When a customer's details or license is updated. -License field conditions have a field, an operator, and a value. The available operators depend on the field type: +### Customer Archived + +When a customer is archived. + +### Customer Unarchived (Restored) + +When a customer is restored from archived state. + +### Customer License Expiring -| 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 | +Time-based warning of an upcoming license expiration. -When multiple license field conditions are specified, all conditions must match for the notification to trigger (AND logic). +### Pending Self-Service Signup +When someone signs up via the self-service portal (if enabled). ## Instance events @@ -79,8 +81,6 @@ The notification triggers when an instance has been in the specified state for a When an instance is changing states frequently within a configured time window. -### Instance state flapping filter requirements - The Instance State Flapping event type requires you to specify the sensitivity of flapping detection: | Filter | Required | Default | Options | @@ -130,31 +130,43 @@ The following frequency options control how often the notification triggers: | 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. | -## Customer events +## Release events -### Customer Created +### Release Created -When a new customer is created. +When a new release is created. -### Customer Updated +### Release Promoted -When a customer's details or license is updated. +When a release is promoted to a channel. -### Customer Archived +### Release Demoted (Unpublished) -When a customer is archived. +When a release is demoted from a channel. -### Customer Unarchived (Restored) +### Release Assets Downloaded -When a customer is restored from archived state. +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. -### Customer License Expiring +The following table describes the available filters for the Release Assets Downloaded event type: -Time-based warning of an upcoming license expiration. +| 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 | -### Pending Self-Service Signup +The **Pull Type** filter controls whether the notification fires on every pull or only the first time a customer pulls any software asset: -When someone signs up via the self-service portal (if enabled). +- **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 @@ -165,31 +177,3 @@ 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. diff --git a/docs/reference/webhooks.md b/docs/reference/webhooks.md new file mode 100644 index 0000000000..034fb1ab75 --- /dev/null +++ b/docs/reference/webhooks.md @@ -0,0 +1,133 @@ +# Webhook payload structure (Beta) + +This topic describes the JSON payload format for event notification webhooks, including details about the fields. + +## Webhook payload structure + +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" + } +} +``` + +## Top-level fields + +The following describes the top-level 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. For common fields, see data object fields below. For fields that vary by event type, see Event-specific fields.

+
+ +## `data` object fields {#data-object-fields} + +The `data` object contains detailed, event-specific information. There are common fields that apply to all event types as well as event-specific fields. + +### Common fields + +The webhook payload includes the following common `data` object fields for all event types: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
app_idstringApplication identifier
team_idstringTeam identifier
app_namestringApplication name
app_slugstringApplication slug (URL-safe identifier)
event_typestringEvent type identifier
subscription_namestringCustom subscription name, if set. The subscription_name field is included in the data object only when a custom name is set on the subscription.
+ +### Event-specific fields {#event-specific-fields} + +This section describes the event-specific fields in the webhok payload `data` object. + +#### Release Assets Downloaded events + +The following fields apply to the [Release Assets Downloaded](/reference/event-types#release-assets-downloaded) event type: + +| 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`. The `is_first_customer_pull` field is useful for revenue recognition workflows. | +| `downloaded_at` | string | Timestamp (International Organization for Standardization (ISO) 8601 format) of when the pull occurred | diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index faace3e35b..d96d4eda02 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -2,23 +2,6 @@ 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: @@ -39,7 +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](/reference/event-types#event-filter-logic-and-requirements). +1. (Optional) For each of the event types that you selected, click the filter icon to configure event filters. For more information, see [About filter logic](#filter-logic) on this page. :::note To configure a channel filter, you must first select an application. @@ -59,7 +42,7 @@ To create an event notification subscription: - 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 **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](/reference/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. diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index c4fd2f0931..4fae288010 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -4,129 +4,49 @@ 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} +For the JSON envelope and field descriptions, see [Event notification webhook payloads (Beta)](/reference/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. +## Configure a Slack webhook -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. +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. -Custom headers have the following limitations: +To send notifications to a Slack channel using webhooks: -- 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 +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. -## 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. -::: +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. ## Verify webhook signatures @@ -174,48 +94,6 @@ To verify webhook signatures in your endpoint: // 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. @@ -228,3 +106,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..4b04d64c56 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -4,15 +4,75 @@ This topic provides an introduction to the Event Notifications (Beta) feature, w ## 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 through email or webhook when a specific event occurs. A single subscription can include one or multiple event types, and each event has its own set of filters. This allows you to create highly-targeted notifications using filters to focus on the events that matter most to your workflow. Events are queued to SQS for reliable processing, and notifications are matched against your custom event filters in real time. -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). +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 create notifications for 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, see [Event types and filters](/reference/event-types). + +### Multi-event notifications + +Each notification can have one or more event types. For notifications that include multiple event types, each event type is evaluated independently against its filters. Any event that matches its filters 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 + +Each event type that you select in a notification subscription has its own set of filters. You can filter events by application, customer, channel, license type, and your custom license field values (entitlements). + +An event must match _all_ specified filters to trigger the notification (AND logic). + +### 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 licese 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 an event. + +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) + +## 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. 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. + +## 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/sidebars.js b/sidebars.js index 700dde2262..339eea049a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -193,8 +193,9 @@ const sidebars = { "vendor/event-notifications", "vendor/event-notifications-create", "reference/event-types", - "vendor/event-notifications-manage", "vendor/event-notifications-webhooks", + "reference/webhooks", + "vendor/event-notifications-manage", ], }, "vendor/instance-notifications-config", From 7bad45793c071cbf7ae4f8aa903a6a8464154f3e Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 19 Mar 2026 15:23:07 -0600 Subject: [PATCH 3/6] file and xref cleanup --- ...pes.md => notifications-events-filters.md} | 8 +++-- ...ks.md => notifications-webhook-payload.md} | 8 ++--- docs/vendor/event-notifications-create.mdx | 16 ++++------ docs/vendor/event-notifications-manage.mdx | 2 +- docs/vendor/event-notifications-webhooks.mdx | 16 ++++------ docs/vendor/event-notifications.mdx | 32 +++++++++---------- sidebars.js | 4 +-- 7 files changed, 40 insertions(+), 46 deletions(-) rename docs/reference/{event-types.md => notifications-events-filters.md} (96%) rename docs/reference/{webhooks.md => notifications-webhook-payload.md} (92%) diff --git a/docs/reference/event-types.md b/docs/reference/notifications-events-filters.md similarity index 96% rename from docs/reference/event-types.md rename to docs/reference/notifications-events-filters.md index 0c435b44bc..922d76f99e 100644 --- a/docs/reference/event-types.md +++ b/docs/reference/notifications-events-filters.md @@ -1,6 +1,8 @@ # Event types and filters (Beta) -This topic lists the types of events supported for the Event Notifications (Beta) feature. For more information about event notifications, see [About event notifications (Beta)](/vendor/event-notifications). +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 @@ -144,7 +146,7 @@ When a release is promoted to a channel. When a release is demoted from a channel. -### Release Assets Downloaded +### 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. @@ -155,7 +157,7 @@ The following table describes the available filters for the Release Assets Downl | 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` | +| 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 | diff --git a/docs/reference/webhooks.md b/docs/reference/notifications-webhook-payload.md similarity index 92% rename from docs/reference/webhooks.md rename to docs/reference/notifications-webhook-payload.md index 034fb1ab75..9a8c97544d 100644 --- a/docs/reference/webhooks.md +++ b/docs/reference/notifications-webhook-payload.md @@ -1,8 +1,8 @@ # Webhook payload structure (Beta) -This topic describes the JSON payload format for event notification webhooks, including details about the fields. +This topic describes the JSON payload format for event notification webhooks, including details about the fields. For more information about the Event Notifications (Beta) feature, see [About event notifications (Beta)](/vendor/event-notifications). -## Webhook payload structure +## Webhook payload structure {#webhook-payload-structure} Webhooks deliver a JSON payload with the following structure: @@ -112,11 +112,11 @@ The webhook payload includes the following common `data` object fields for all e ### Event-specific fields {#event-specific-fields} -This section describes the event-specific fields in the webhok payload `data` object. +This section describes the event-specific fields in the webhook payload `data` object. #### Release Assets Downloaded events -The following fields apply to the [Release Assets Downloaded](/reference/event-types#release-assets-downloaded) event type: +The following fields apply to the [Release Assets Downloaded](/reference/notifications-events-filters#release-assets-downloaded) event type: | Field | Type | Description | |-------|------|-------------| diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index d96d4eda02..0593abebe9 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -1,6 +1,6 @@ # Create event notification subscriptions (Beta) -This topic describes how to create event notification subscriptions in the Replicated Vendor Portal. +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 @@ -14,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 (Beta)](/reference/event-types). +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. @@ -22,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 [About filter logic](#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**. @@ -40,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](/reference/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). + 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 [Webhook payload structure (Beta)](/reference/notifications-webhook-payload). 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. 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 4fae288010..635ecb71bb 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -1,10 +1,8 @@ # Configure and use webhooks (Beta) -This topic describes how to configure and use webhooks for Event Notifications. +This topic describes how to configure and use webhooks for event notifications. For more information about the Event Notifications (Beta) feature, see [About event notifications (Beta)](/vendor/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. - -For the JSON envelope and field descriptions, see [Event notification webhook payloads (Beta)](/reference/webhooks). +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. For the JSON envelope and field descriptions, see [Webhook payload structure (Beta)](/reference/notifications-webhook-payload). ## Configure a Slack webhook @@ -16,23 +14,21 @@ To send notifications to a Slack channel using webhooks: 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. Create a notification 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. +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). -Note the following: +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 -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: +1. Use a tunnel service like [ngrok](https://ngrok.com/docs/start) to expose your local endpoint: ```bash ngrok http 3000 diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index 4b04d64c56..8e2df28f3e 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -1,12 +1,12 @@ # 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 -You can define and subscribe to notifications in the Vendor Portal to receive alerts through email or webhook when a specific event occurs. A single subscription can include one or multiple event types, and each event has its own set of filters. This allows you to create highly-targeted notifications using filters to focus on the events that matter most to your workflow. Events are queued to SQS for reliable processing, and notifications are matched against your custom event filters in real time. +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. -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 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 and filters @@ -14,23 +14,21 @@ This section describes the types of events and filters that are available for cr ### Supported event types -You can create notifications for various types of events, including events related to application instances, customers, support bundles, releases, and channels. +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 create notifications for 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 example, you can create notifications for 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, see [Event types and filters](/reference/event-types). +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 event types. For notifications that include multiple event types, each event type is evaluated independently against its filters. Any event that matches its filters triggers a notification. +Each notification can have one or more events. For notifications that include multiple events, each event is evaluated 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 -Each event type that you select in a notification subscription has its own set of filters. You can filter events by application, customer, channel, license type, and your custom license field values (entitlements). +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). -An event must match _all_ specified 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 @@ -40,12 +38,14 @@ For example, if you select both **Paid** and **Community** for the **License typ ### Custom licese 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 an event. +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. 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) +- 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 @@ -62,11 +62,11 @@ For teams that use custom RBAC policies, the following permissions are available - `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). +For more information, see [Configure RBAC policies](team-management-rbac-configuring#configure-a-custom-rbac-policy). ## Limitations -Event Notifications (Beta) has the following 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. diff --git a/sidebars.js b/sidebars.js index 339eea049a..27e95e7a4e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -192,9 +192,9 @@ const sidebars = { items: [ "vendor/event-notifications", "vendor/event-notifications-create", - "reference/event-types", + "reference/notifications-events-filters", "vendor/event-notifications-webhooks", - "reference/webhooks", + "reference/notifications-webhook-payload", "vendor/event-notifications-manage", ], }, From b2fef8c3653c1c9c87b9ce3e3681b543c8da9402 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 19 Mar 2026 15:28:23 -0600 Subject: [PATCH 4/6] don't link notifications reference docs --- .github/workflows/vale-pr-review.yml | 1 + .vale.ini | 4 ++++ docs/reference/notifications-webhook-payload.md | 4 ++-- 3 files changed, 7 insertions(+), 2 deletions(-) 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-webhook-payload.md b/docs/reference/notifications-webhook-payload.md index 9a8c97544d..c7cf03ec6a 100644 --- a/docs/reference/notifications-webhook-payload.md +++ b/docs/reference/notifications-webhook-payload.md @@ -43,7 +43,7 @@ The following describes the top-level fields in the webhook payload: `event` string - Event type identifier (e.g., "customer.created", "instance.upgrade_started") + Event type identifier such as "customer.created" or "instance.upgrade_started" `timestamp` @@ -59,7 +59,7 @@ The following describes the top-level fields in the webhook payload: `data` object -

Event-specific data containing detailed information about the event. For common fields, see data object fields below. For fields that vary by event type, see Event-specific fields.

+

Event-specific data containing detailed information about the event. See data object fields on this page.

From b581283d8fe9d293965609b69528329ba7416e51 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 19 Mar 2026 15:46:20 -0600 Subject: [PATCH 5/6] vale linter --- docs/vendor/event-notifications.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/vendor/event-notifications.mdx b/docs/vendor/event-notifications.mdx index 8e2df28f3e..8955c90700 100644 --- a/docs/vendor/event-notifications.mdx +++ b/docs/vendor/event-notifications.mdx @@ -6,7 +6,7 @@ This topic provides an overview of the Event Notifications (Beta) feature, which 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. -Events are queued to SQS for reliable processing, and notifications are matched 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). +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 and filters @@ -14,13 +14,13 @@ This section describes the types of events and filters that are available for cr ### 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 create notifications for 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. +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, each event is evaluated independently against its filters. If any event matches its filters, then the Vendor Portal triggers a notification. +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. @@ -36,11 +36,11 @@ If a single filter has multiple values, then the event must match _any_ of the s 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 licese field filters +### 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. -Filtering by custom license fields is supported for the following event types: +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) @@ -70,7 +70,7 @@ 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. 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 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) From e2cb2b54de1208b005a7de12b9678b0ab8119177 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 24 Mar 2026 12:01:40 -0600 Subject: [PATCH 6/6] remove webhook payload reference page --- .../notifications-webhook-payload.md | 133 ------------------ docs/vendor/event-notifications-create.mdx | 6 +- docs/vendor/event-notifications-webhooks.mdx | 23 +-- docs/vendor/team-management-slack-config.mdx | 2 +- sidebars.js | 1 - 5 files changed, 17 insertions(+), 148 deletions(-) delete mode 100644 docs/reference/notifications-webhook-payload.md diff --git a/docs/reference/notifications-webhook-payload.md b/docs/reference/notifications-webhook-payload.md deleted file mode 100644 index c7cf03ec6a..0000000000 --- a/docs/reference/notifications-webhook-payload.md +++ /dev/null @@ -1,133 +0,0 @@ -# Webhook payload structure (Beta) - -This topic describes the JSON payload format for event notification webhooks, including details about the fields. For more information about the Event Notifications (Beta) feature, see [About event notifications (Beta)](/vendor/event-notifications). - -## Webhook payload structure {#webhook-payload-structure} - -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" - } -} -``` - -## Top-level fields - -The following describes the top-level fields in the webhook payload: - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
`event`stringEvent type identifier such as "customer.created" or "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. See data object fields on this page.

-
- -## `data` object fields {#data-object-fields} - -The `data` object contains detailed, event-specific information. There are common fields that apply to all event types as well as event-specific fields. - -### Common fields - -The webhook payload includes the following common `data` object fields for all event types: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDescription
app_idstringApplication identifier
team_idstringTeam identifier
app_namestringApplication name
app_slugstringApplication slug (URL-safe identifier)
event_typestringEvent type identifier
subscription_namestringCustom subscription name, if set. The subscription_name field is included in the data object only when a custom name is set on the subscription.
- -### Event-specific fields {#event-specific-fields} - -This section describes the event-specific fields in the webhook payload `data` object. - -#### Release Assets Downloaded events - -The following fields apply to the [Release Assets Downloaded](/reference/notifications-events-filters#release-assets-downloaded) event type: - -| 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`. The `is_first_customer_pull` field is useful for revenue recognition workflows. | -| `downloaded_at` | string | Timestamp (International Organization for Standardization (ISO) 8601 format) of when the pull occurred | diff --git a/docs/vendor/event-notifications-create.mdx b/docs/vendor/event-notifications-create.mdx index 0593abebe9..56491f3128 100644 --- a/docs/vendor/event-notifications-create.mdx +++ b/docs/vendor/event-notifications-create.mdx @@ -36,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 [Webhook payload structure (Beta)](/reference/notifications-webhook-payload). + 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. diff --git a/docs/vendor/event-notifications-webhooks.mdx b/docs/vendor/event-notifications-webhooks.mdx index 635ecb71bb..7caf72ca1a 100644 --- a/docs/vendor/event-notifications-webhooks.mdx +++ b/docs/vendor/event-notifications-webhooks.mdx @@ -1,20 +1,23 @@ -# Configure and use webhooks (Beta) +# Configure and test webhooks (Beta) -This topic describes how to configure and use webhooks for event notifications. For more information about the Event Notifications (Beta) feature, see [About event notifications (Beta)](/vendor/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. For the JSON envelope and field descriptions, see [Webhook payload structure (Beta)](/reference/notifications-webhook-payload). +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. -## Configure a Slack 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 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. 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 a notification in the Vendor Portal using your Slack webhook URL. See [Create an event notification](/vendor/event-notifications-create#create-an-event-notification). +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} 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 27e95e7a4e..d21d0c3939 100644 --- a/sidebars.js +++ b/sidebars.js @@ -194,7 +194,6 @@ const sidebars = { "vendor/event-notifications-create", "reference/notifications-events-filters", "vendor/event-notifications-webhooks", - "reference/notifications-webhook-payload", "vendor/event-notifications-manage", ], },