feat: move webhooks to own section; add slack example template (#156)

* feat: move webhooks to own section; add slack example template * chore: format code * chore: yaml codeticks * chore: format code --------- Co-authored-by: markphelps <[email protected]>
flipt-io · Dec 11, 2023 · cbd330c · cbd330c
1 parent 9ceb05a
commit cbd330c
Show file tree

Hide file tree

Showing 5 changed files with 107 additions and 72 deletions.
diff --git a/.vale/styles/Flipt/spelling-exceptions.txt b/.vale/styles/Flipt/spelling-exceptions.txt
@@ -43,6 +43,7 @@ otlp
 performant
 PGBouncer
 postgres
+pprof
 protobuf
 protoc
 Quicksort

diff --git a/configuration/auditing/overview.mdx b/configuration/auditing/overview.mdx
@@ -0,0 +1,66 @@
+---
+title: Overview
+description: This document describes Flipt's auditing capabilities.
+---
+
+Audit Events are pieces of data that describe a particular thing that has happened in a system. At Flipt, we provide the functionality of processing and batching these audit events and an abstraction for sending these audit events to a sink.
+
+## Events
+
+Flipt supports sending audit events to configured sinks. Audit events have the following structure:
+
+```json
+{
+  "version": "0.1",
+  "type": "flag",
+  "action": "created",
+  "metadata": {
+    "actor": {
+      "authentication": "none",
+      "ip": "172.17.0.1"
+    }
+  },
+  "payload": {
+    "description": "flipt flag",
+    "enabled": true,
+    "key": "flipt",
+    "name": "flipt",
+    "namespace_key": "default"
+  },
+  "timestamp": "1970-01-01T00:00:00Z"
+}
+```
+
+- `version` : the version of the audit event structure. We don't expect too many changes to the structure of the audit event
+- `type` : the type of the entity being acted upon (flag, variant, constraint, etc.)
+- `action` : the action taken upon the entity (created, deleted, updated, etc.)
+- `metadata` : extra information related to the audit event as a whole. The `actor` field will always be present containing some identity information of the source which initiated the audit event
+- `payload` : the actual payload used to interact with the `Flipt` server for certain auditable events
+- `timestamp`: the time the event was created
+
+Currently, we support the following sinks for audit events:
+
+- Log File: the audit events are JSON encoded and new-line delimited. You can find the configuration in the [Audit Events - Log File](/configuration/overview#audit-events-log-file) section of the Configuration documentation.
+
+- Webhook: the audit events are sent to a URL of your choice. You can find the configuration in the [Audit Events - Webhook](/configuration/overview#audit-events-webhook) section of the Configuration documentation.
+
+You can find [examples](https://github.com/flipt-io/flipt/tree/main/examples/audit) in the main GitHub repository on how to enable audit events and how to tune configuration for it.
+
+## Event Filtering
+
+Starting from [v1.27.0](https://github.com/flipt-io/flipt/releases/tag/v1.27.0), you can specify configuration for which events you would like to receive on your audit sink.
+
+An always up to date list of events supported is available in our [GitHub repository](https://github.com/flipt-io/flipt/blob/main/internal/server/audit/README.md).
+
+Events are specified in the format of `noun:verb`. You can also specify a wild card for either the noun or the verb. For instance `*:created` corresponds to all `created` events for every entity. Furthermore, `flag:*` corresponds to all `flag` events, and `*:*` corresponds to every single event.
+
+Examples of configuring events include:
+
+```
+flag:created
+namespace:created
+flag:*
+rollout:deleted
+rule:deleted
+*:updated
+```
diff --git a/configuration/auditing.mdx → configuration/auditing/webhooks.mdx b/configuration/auditing.mdx → configuration/auditing/webhooks.mdx
@@ -1,72 +1,8 @@
 ---
-title: Auditing
-description: This document describes Flipt's auditing capabilities.
+title: Webhooks
+description: This document describes Flipt's webhook support.
 ---
 
-Audit Events are pieces of data that describe a particular thing that has happened in a system. At Flipt, we provide the functionality of processing and batching these audit events and an abstraction for sending these audit events to a sink.
-
-## Audit Events
-
-Flipt supports sending audit events to configured sinks. Audit events have the following structure:
-
-```json
-{
-  "version": "0.1",
-  "type": "flag",
-  "action": "created",
-  "metadata": {
-    "actor": {
-      "authentication": "none",
-      "ip": "172.17.0.1"
-    }
-  },
-  "payload": {
-    "description": "flipt flag",
-    "enabled": true,
-    "key": "flipt",
-    "name": "flipt",
-    "namespace_key": "default"
-  },
-  "timestamp": "1970-01-01T00:00:00Z"
-}
-```
-
-- `version` : the version of the audit event structure. We don't expect too many changes to the structure of the audit event
-- `type` : the type of the entity being acted upon (flag, variant, constraint, etc.)
-- `action` : the action taken upon the entity (created, deleted, updated, etc.)
-- `metadata` : extra information related to the audit event as a whole. The `actor` field will always be present containing some identity information of the source which initiated the audit event
-- `payload` : the actual payload used to interact with the `Flipt` server for certain auditable events
-- `timestamp`: the time the event was created
-
-Currently, we support the following sinks for audit events:
-
-- Log File: the audit events are JSON encoded and new-line delimited. You can find the configuration in the [Audit Events - Log File](/configuration/overview#audit-events-log-file) section of the Configuration documentation.
-
-- Webhook: the audit events are sent to a URL of your choice. You can find the configuration in the [Audit Events - Webhook](/configuration/overview#audit-events-webhook) section of the Configuration documentation.
-
-You can find [examples](https://github.com/flipt-io/flipt/tree/main/examples/audit) in the main GitHub repository on how to enable audit events and how to tune configuration for it.
-
-## Event Filtering
-
-Starting from [v1.27.0](https://github.com/flipt-io/flipt/releases/tag/v1.27.0), you can specify configuration for which events you would like to receive on your audit sink.
-
-An always up to date list of events supported is available in our [GitHub repository](https://github.com/flipt-io/flipt/blob/main/internal/server/audit/README.md).
-
-Events are specified in the format of `noun:verb`. You can also specify a wild card for either the noun or the verb. For instance `*:created` corresponds to all `created` events for every entity. Furthermore, `flag:*` corresponds to all `flag` events, and `*:*` corresponds to every single event.
-
-Examples of configuring events include:
-
-```
-flag:created
-namespace:created
-flag:*
-rollout:deleted
-rule:deleted
-*:updated
-```
-
-## Webhooks
-
 You can opt to receive audit events as an HTTP POST to a configured webhook.
 
 Below is an example HTTP POST request made to a webhook URL:
@@ -100,7 +36,7 @@ X-Forwarded-Proto: https
 }
 ```
 
-### Automatic Retries
+## Automatic Retries
 
 If the webhook server returns a non-200 response, Flipt will retry sending the request using an exponential backoff strategy until a maximum elapsed duration. The default maximum elapsed duration is 15 seconds.
 
@@ -115,13 +51,13 @@ audit:
 
 See the [Audit Events - Webhook](/configuration/overview#audit-events-webhook) section of the configuration documentation for more details.
 
-### Security
+## Security
 
 You may provide a signing secret for requests to your webhook. If you specify a signing secret, you will receive a request with the `X-Flipt-Webhook-Signature` header populated. This value can be set in the [Audit Events - Webhook](/configuration/overview#audit-events-webhook) section of the Flipt server configuration.
 
 The value in the `X-Flipt-Webhook-Signature` header is the request body HMAC SHA256 signed with the signing secret you specified. On the webhook server, you can validate the signature by using the same signing secret. It's _strongly recommended_ that you do this to prevent requests to your webhook server that are from invalid origins.
 
-### Templates
+## Templates
 
 Starting from [v1.28.0](https://github.com/flipt-io/flipt/releases/tag/v1.28.0), you can specify a template for the body of an Audit Event Webhook request.
 
@@ -160,4 +96,29 @@ type Event struct {
 }
 ```
 
-Any of the values that are [exposed](https://github.com/flipt-io/flipt/blob/v1.28.0/internal/server/audit/audit.go#L51-L61) by Flipt are fair game for inclusion in your HTTP body template.
+Any of the values that are [exposed](https://github.com/flipt-io/flipt/blob/v1.28.0/internal/server/audit/audit.go#L51-L61) by Flipt are available for inclusion in your HTTP body template.
+
+### Example: Slack
+
+Below is an example of a Slack webhook integration that uses the templating feature to send a Slack message when a flag is updated.
+
+````yaml
+audit:
+  sinks:
+    webhook:
+      enabled: true
+      templates:
+        - url: "https://hooks.slack.com/services/xxxxx"
+          headers:
+            Content-Type: "application/json"
+          body: |
+            {
+              "text": "Flipt Event: {{.Type}}/{{.Action}}\n\n```{{.Payload }}```"
+            }
+````
+
+The above configuration will send a Slack message that looks like this:
+
+![Slack Message](/images/configuration/auditing/slack-webhook.png)
+
+You can find more information about Slack webhooks [here](https://api.slack.com/messaging/webhooks). You can also use the [Slack Block Kit Builder](https://app.slack.com/block-kit-builder) to build more complex messages.
diff --git a/images/configuration/auditing/slack-webhook.png b/images/configuration/auditing/slack-webhook.png
diff --git a/mint.json b/mint.json
@@ -113,10 +113,17 @@
       "pages": [
         "configuration/overview",
         "configuration/authentication",
-        "configuration/auditing",
         "configuration/observability",
         "configuration/storage",
-        "configuration/telemetry"
+        "configuration/telemetry",
+        {
+          "group": "Auditing",
+          "pages": [
+            "configuration/auditing/overview",
+            "configuration/auditing/webhooks"
+          ]
+
+        }
       ]
     },
     {