Event notifications reference docs

.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: " "
 

.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 =

docs/reference/notifications-events-filters.md

@@ -0,0 +1,181 @@
+# Event types and filters (Beta)
+
+For more information about the Event Notifications (Beta) feature, see [About event notifications (Beta)](/vendor/event-notifications).
+
+This topic lists the types of events supported for the Event Notifications (Beta) feature.
+
+## Channel events
+
+### Channel Created
+
+When a new channel is created for an application.
+
+### Channel Archived
+
+When a channel is archived.
+
+## Customer events
+
+### Customer Created
+
+When a new customer is created.
+
+### Customer Updated
+
+When a customer's details or license is updated.
+
+### Customer Archived
+
+When a customer is archived.
+
+### Customer Unarchived (Restored)
+
+When a customer is restored from archived state.
+
+### Customer License Expiring
+
+Time-based warning of an upcoming license expiration.
+
+### Pending Self-Service Signup
+
+When someone signs up via the self-service portal (if enabled).
+
+## Instance events
+
+### Instance Created
+
+When a new instance sends its first check-in.
+
+### Instance Ready
+
+When a new instance's application status is Ready for the first time.
+
+### Instance Upgrade Started
+
+When an instance begins upgrading to a new release version. This event fires when the Vendor Portal receives the first telemetry with a new release version, whether or not the application status is Ready.
+
+### Instance Upgrade Completed
+
+When an instance's application status is Ready after upgrading to a new release version.
+
+### Instance Version Behind
+
+When an instance falls behind by a specified number of versions.
+
+### Instance Inactive
+
+When an instance has not checked-in for 24 hours (declared "Inactive"). Air-gapped instances are excluded from this event type.
+
+### Instance State Duration
+
+When an instance has been in a specific state (such as Unavailable or Degraded) for a specified duration.
+
+The Instance State Duration event type requires you to specify the target state and duration threshold. Only one Instance State Duration event is allowed per subscription.
+
+| Filter | Required | Options |
+|--------|----------|---------|
+| State | Yes | Ready, Unavailable, Degraded, Updating, Missing |
+| Duration | Yes | 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours, 24 hours |
+
+The notification triggers when an instance has been in the specified state for at least the configured duration. If the instance recovers and later re-enters the monitored state, the notification can trigger again after the duration threshold is met.
+
+### Instance State Flapping
+
+When an instance is changing states frequently within a configured time window.
+
+The Instance State Flapping event type requires you to specify the sensitivity of flapping detection:
+
+| Filter | Required | Default | Options |
+|--------|----------|---------|---------|
+| Minimum State Changes | Yes | — | 3, 5, 10, 15, 20 |
+| Time Window | Yes | — | 30 minutes, 1 hour, 2 hours |
+| Cooldown Period | No | 1 hour | 15 minutes, 30 minutes, 1 hour, 2 hours, 1 day |
+
+The notification triggers when an instance accumulates the specified number of state changes within the time window. The cooldown period prevents repeated notifications for the same instance within the configured interval.
+
+### Custom Metric Threshold Reached
+
+When a custom metric value reported by an instance meets a configured threshold condition.
+
+:::note
+Instance event notifications use the **Instance Name** if set. Otherwise, they use the Instance ID.
+:::
+
+The Custom Metric Threshold Reached event type requires a metric name, comparison operator, and notification frequency. You can include only one Custom Metric Threshold Reached event per subscription.
+
+The following table describes each of the filters for the Custom Metric Threshold Reached event type:
+
+| Filter | Required | Description |
+|--------|----------|-------------|
+| Metric Name | Yes | Select from previously reported custom metrics or enter a metric name manually |
+| Operator | Yes | Comparison operator. The operators available depend on the metric type. For more information, see [Available operators](#available-operators). |
+| Threshold Value | Conditional | Required for all operators except `is_true`, `is_false`, `exists`, and `not_exists` |
+| Frequency | Yes | Controls how often you receive the notification. For more information, see [Frequency options](#frequency-options). |
+
+#### Available operators
+
+The available operators depend on the type of metric value:
+
+| Metric Type | Available Operators |
+|-------------|-------------------|
+| Number | greater than, greater than or equal, less than, less than or equal, equals, does not equal, exists, does not exist |
+| Boolean | is true, is false, equals, does not equal, exists, does not exist |
+| String | contains, starts with, ends with, equals, does not equal, exists, does not exist |
+
+#### Frequency options
+
+The following frequency options control how often the notification triggers:
+
+| Frequency | Behavior |
+|-----------|----------|
+| Send Once | Notifies the first time the metric meets the threshold. Does not notify again until the condition clears and the metric meets the threshold again. |
+| When Changed | Notifies when the metric meets the threshold and its value has changed since the last notification. |
+| Each Time | Notifies every time a metric report meets the threshold condition. |
+
+## Release events
+
+### Release Created
+
+When a new release is created.
+
+### Release Promoted
+
+When a release is promoted to a channel.
+
+### Release Demoted (Unpublished)
+
+When a release is demoted from a channel.
+
+### Release Assets Downloaded {#release-assets-downloaded}
+
+When a customer pulls a release asset (Helm chart, Embedded Cluster bundle, or proxy registry image). Fires one time per individual asset pull. Includes whether this is the customer's first ever software pull, which is useful for revenue recognition tracking.
+
+The following table describes the available filters for the Release Assets Downloaded event type:
+
+| Filter | Required | Options |
+|--------|----------|---------|
+| Application | No | Any application in your account |
+| Channel | No | Any channel for the selected application |
+| Customer | No | Any customer for the selected application |
+| License Type | No | Paid, Trial, Community, Development |
+| Asset Type | No | Helm Chart, Embedded Cluster Bundle, Proxy Registry Image |
+| Pull Type | No | First Pull Only, Any Pull |
+
+The **Pull Type** filter controls whether the notification fires on every pull or only the first time a customer pulls any software asset:
+
+- **First Pull Only**: The notification fires only when a customer pulls a release asset for the first time, across all asset types. Use this to track the revenue recognition milestone when a customer first retrieves your software.
+- **Any Pull** (default): The notification fires on every pull. This is equivalent to leaving the filter unset, and all existing subscriptions behave this way.
+
+:::note
+First pull tracking is forward-only. Customers who pulled software before this feature shipped will have `is_first_customer_pull: false` on all subsequent pulls.
+:::
+
+## Support events
+
+### Support Bundle Uploaded
+
+When a support bundle is uploaded.
+
+### Support Bundle Analyzed
+
+When a support bundle analysis is completed.

docs/reference/notifications-webhook-payload.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. 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:
+
+<table>
+  <tr>
+    <th>Field</th>
+    <th>Type</th>
+    <th>Description</th>
+   </tr>
+  <tr>
+    <td>`event`</td>
+    <td>string</td>
+    <td>Event type identifier such as "customer.created" or "instance.upgrade_started"</td>
+   </tr>
+  <tr>
+    <td>`timestamp`</td>
+    <td>string</td>
+    <td>ISO 8601 timestamp when the event occurred</td>
+   </tr>
+  <tr>
+    <td>`text`</td>
+    <td>string</td>
+    <td>Human-readable text description of the event, formatted for readability in Slack and other chat tools</td>
+    </tr>
+  <tr>
+    <td>`data`</td>
+    <td>object</td>
+    <td>
+      <p>Event-specific data containing detailed information about the event. See <a href="#data-object-fields"><code>data</code> object fields</a> on this page.</p>
+    </td>
+   </tr>
+</table>
+
+## `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:
+
+<table>
+  <tr>
+    <th>Field</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>app_id</code></td>
+    <td>string</td>
+    <td>Application identifier</td>
+  </tr>
+  <tr>
+    <td><code>team_id</code></td>
+    <td>string</td>
+    <td>Team identifier</td>
+  </tr>
+  <tr>
+    <td><code>app_name</code></td>
+    <td>string</td>
+    <td>Application name</td>
+  </tr>
+  <tr>
+    <td><code>app_slug</code></td>
+    <td>string</td>
+    <td>Application slug (URL-safe identifier)</td>
+  </tr>
+  <tr>
+    <td><code>event_type</code></td>
+    <td>string</td>
+    <td>Event type identifier</td>
+  </tr>
+  <tr>
+    <td><code>subscription_name</code></td>
+    <td>string</td>
+    <td>Custom subscription name, if set. The <code>subscription_name</code> field is included in the <code>data</code> object only when a custom name is set on the subscription.</td>
+  </tr>
+</table>
+
+### 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 |