Documentation & changelog for #6238

docs/models/extras/webhook.md

@@ -17,6 +17,7 @@ A webhook is a mechanism for conveying to some external system a change that too
 * **Additional headers** - Any additional headers to include with the request (optional). Add one header per line in the format `Name: Value`. Jinja2 templating is supported for this field (see below).
 * **Body template** - The content of the request being sent (optional). Jinja2 templating is supported for this field (see below). If blank, NetBox will populate the request body with a raw dump of the webhook context. (If the HTTP cotent type is set to `application/json`, this will be formatted as a JSON object.)
 * **Secret** - A secret string used to prove authenticity of the request (optional). This will append a `X-Hook-Signature` header to the request, consisting of a HMAC (SHA-512) hex digest of the request body using the secret as the key.
+* **Conditions** - An optional set of conditions evaluated to determine whether the webhook fires for a given object.
 * **SSL verification** - Uncheck this option to disable validation of the receiver's SSL certificate. (Disable with caution!)
 * **CA file path** - The file path to a particular certificate authority (CA) file to use when validating the receiver's SSL certificate (optional).
 
@@ -80,3 +81,16 @@ If no body template is specified, the request body will be populated with a JSON
     }
 }
 ```
+
+## Conditional Webhooks
+
+A webhook may include a set of conditional logic expressed in JSON used to control whether a webhook triggers for a specific object. For example, you may wish to trigger a webhook for devices only when the `status` field of an object is "active":
+
+```json
+{
+  "attr": "status",
+  "value": "active"
+}
+```
+
+For more detail, see the reference documentation for NetBox's [conditional logic](../reference/conditions.md).

docs/reference/conditions.md

@@ -0,0 +1,89 @@
+# Conditions
+
+Conditions are NetBox's mechanism for evaluating whether a set data meets a prescribed set of conditions. It allows the author to convey simple logic by declaring an arbitrary number of attribute-value-operation tuples nested within a hierarchy of logical AND and OR statements.
+
+## Conditions
+
+A condition is expressed as a JSON object with the following keys:
+
+| Key name | Required | Default | Description |
+|----------|----------|---------|-------------|
+| attr     | Yes      | -       | Name of the key within the data being evaluated |
+| value    | Yes      | -       | The reference value to which the given data will be compared |
+| op       | No       | `eq`    | The logical operation to be performed |
+| negate   | No       | False   | Negate (invert) the result of the condition's evaluation |
+
+### Available Operations
+
+* `eq`: Equals
+* `gt`: Greater than
+* `gte`: Greater than or equal to
+* `lt`: Less than
+* `lte`: Less than or equal to
+* `in`: Is present within a list of values
+* `contains`: Contains the specified value
+
+### Examples
+
+`name` equals "foobar":
+
+```json
+{
+  "attr": "name",
+  "value": "foobar"
+}
+```
+
+`asn` is greater than 65000:
+
+```json
+{
+  "attr": "asn",
+  "value": 65000,
+  "op": "gt"
+}
+```
+
+`status` is not "planned" or "staging":
+
+```json
+{
+  "attr": "status",
+  "value": ["planned", "staging"],
+  "op": "in",
+  "negate": true
+}
+```
+
+## Condition Sets
+
+Multiple conditions can be combined into nested sets using AND or OR logic. This is done by declaring a JSON object with a single key (`and` or `or`) containing a list of condition objects and/or child condition sets.
+
+### Examples
+
+`status` is "active" and `primary_ip` is defined _or_ the "exempt" tag is applied.
+
+```json
+{
+  "or": [
+    {
+      "and": [
+        {
+          "attr": "status",
+          "value": "active"
+        },
+        {
+          "attr": "primary_ip",
+          "value": "",
+          "negate": true
+        }
+      ]
+    },
+    {
+      "attr": "tags",
+      "value": "exempt",
+      "op": "contains"
+    }
+  ]
+}
+```

docs/release-notes/version-3.1.md

@@ -28,6 +28,20 @@ Both types of connection include SSID and authentication attributes. Additionall
 * Channel - A predefined channel within a standardized band
 * Channel frequency & width - Customizable channel attributes (e.g. for licensed bands)
 
+#### Conditional Webhooks ([#6238](https://github.com/netbox-community/netbox/issues/6238))
+
+Webhooks now include a `conditions` field, which may be used to specify conditions under which a webhook triggers. For example, you may wish to generate outgoing requests for a device webhook only when its status is "active" or "staged". This can be done by declaring conditional logic in JSON:
+
+```json
+{
+  "attr": "status",
+  "op": "in",
+  "value": ["active", "staged"]
+}
+```
+
+Multiple conditions may be nested using AND/OR logic as well. For more information, please see the [conditional logic documentation](../reference/conditions.md). 
+
 #### Interface Bridging ([#6346](https://github.com/netbox-community/netbox/issues/6346))
 
 A `bridge` field has been added to the interface model for devices and virtual machines. This can be set to reference another interface on the same parent device/VM to indicate a direct layer two bridging adjacency.
@@ -85,5 +99,7 @@ Multiple interfaces can be bridged to a single virtual interface to effect a bri
     * Added `wwn` field
 * dcim.Location
     * Added `tenant` field
+* extras.Webhook
+    * Added the `conditions` field
 * virtualization.VMInterface
     * Added `bridge` field

mkdocs.yml

@@ -93,6 +93,8 @@ nav:
         - Authentication: 'rest-api/authentication.md'
     - GraphQL API:
         - Overview: 'graphql-api/overview.md'
+    - Reference:
+        - Conditions: 'reference/conditions.md'
     - Development:
         - Introduction: 'development/index.md'
         - Getting Started: 'development/getting-started.md'