docs: enhance webhook documentation for audit logs and environment settings

docs/docs/administration-and-security/governance-and-compliance/audit-logs.md

@@ -10,14 +10,75 @@ retrace the events and values that flags, identities and segments have taken ove
 You can view the Audit Log within the Flagsmith application, and filter it in order to find the information you are
 after.
 
-## Audit Log Web Hooks
+## Audit Log Webhooks
 
-You can also stream your Audit Logs into your own infrastructure using
-[Audit Log Web Hooks](/third-party-integrations/webhook#audit-log-webhooks).
+You can stream your Audit Logs into your own infrastructure using Audit Log Webhooks. This is useful for:
+- **Compliance**: Maintaining audit trails in your own systems for regulatory requirements
+- **CI/CD integration**: Referencing audit log events in your local CI/CD infrastructure
+- **Security monitoring**: Tracking all changes across your projects in real-time
 
-## Event Types
+### Setup
 
-Flagsmith records the following events into the Audit Log.
+1. Configure a webhook endpoint in your infrastructure that accepts POST requests with the [JSON schema](#audit-log-webhook-payload) below.
+2. Add the webhook URL in your Flagsmith organisation settings.
+3. Optionally provide a Secret which will be [hashed and included in the HTTP header](#webhook-signature) to verify that the webhook has come from Flagsmith.
+
+All audit log events will be sent to your webhook URL as they occur.
+
+### Audit Log Webhook Payload
+
+Flagsmith will send a `POST` request to your webhook URL with the following payload in the body:
+
+```json
+{
+ "created_date": "2020-02-23T17:30:57.006318Z",
+ "log": "New Flag / Remote Config created: my_feature",
+ "author": {
+  "id": 3,
+  "email": "user@domain.com",
+  "first_name": "Kyle",
+  "last_name": "Johnson"
+ },
+ "environment": null,
+ "project": {
+  "id": 6,
+  "name": "Project name",
+  "organisation": 1
+ },
+ "related_object_id": 6,
+ "related_object_type": "FEATURE"
+}
+```
+
+### Webhook Signature
+
+When your webhook secret is set, Flagsmith uses it to create a hash signature with each payload. This hash signature is passed with each request under the `X-Flagsmith-Signature` header that you need to validate at your end.
+
+#### Validating Signature
+
+Compute an HMAC with the SHA256 hash function. Use request body (raw utf-8 encoded string) as the message and secret (utf8 encoded) as the Key. Here is one example in Python:
+
+```python
+import hmac
+import hashlib
+
+secret = "my shared secret"
+
+expected_signature = hmac.new(
+    key=secret.encode(),
+    msg=request_body,
+    digestmod=hashlib.sha256,
+).hexdigest()
+
+received_signature = request["headers"]["x-flagsmith-signature"]
+hmac.compare_digest(expected_signature, received_signature) is True
+```
+
+---
+
+## Audit Log Event Types
+
+The following sections describe the types of events that are recorded in the Audit Log (both in the Flagsmith application and via webhooks):
 
 ### Environments
 

docs/docs/administration-and-security/platform-configuration/environment-settings.md

@@ -19,6 +19,118 @@ split operator) when evaluated against the remote API. Evaluations in local eval
 
 :::
 
+## Environment Webhooks
+
+Environment webhooks allow you to send flag change events from Flagsmith into your own infrastructure. Webhooks are managed at an Environment level and can be configured in the Environment settings page.
+
+This is particularly useful for:
+- **Custom caching behaviour**: Updating your local cache when flags change in an environment
+- **Real-time synchronisation**: Keeping external systems in sync with flag states
+- **Event-driven architectures**: Triggering downstream processes when flags are updated
+
+### Setup
+
+1. Configure a webhook endpoint in your infrastructure that accepts POST requests with the [JSON schema](#environment-webhook-payload) below.
+2. Add the webhook URL in your Environment settings.
+3. Optionally provide a Secret which will be [hashed and included in the HTTP header](#webhook-signature) to verify that the webhook has come from Flagsmith.
+
+You can define any number of webhook endpoints per environment. Each event will generate an HTTP POST to all configured webhook URLs.
+
+### Events That Trigger Webhooks
+
+The following events will generate a webhook action (all sent as `event_type: "FLAG_UPDATED"`):
+
+- Creating a new feature
+- Updating a feature value/state in an environment
+- Overriding a feature for an identity
+- Overriding a feature for a segment
+
+### Environment Webhook Payload
+
+Flagsmith will send a `POST` request to your webhook URL with the following payload in the body:
+
+```json
+{
+ "data": {
+  "changed_by": "user@domain.com",
+  "new_state": {
+   "enabled": true,
+   "environment": {
+    "id": 23,
+    "name": "Development"
+   },
+   "feature": {
+    "created_date": "2021-02-10T20:03:43.348556Z",
+    "default_enabled": false,
+    "description": "Show html in a butter bar for certain users",
+    "id": 7168,
+    "initial_value": null,
+    "name": "butter_bar",
+    "project": {
+     "id": 12,
+     "name": "Flagsmith Website"
+    },
+    "type": "CONFIG"
+   },
+   "feature_segment": null,
+   "feature_state_value": "<strong>\nYou are using the develop environment.\n</strong>",
+   "identity": null,
+   "identity_identifier": null
+  },
+  "previous_state": {
+   "enabled": false,
+   "environment": {
+    "id": 23,
+    "name": "Development"
+   },
+   "feature": {
+    "created_date": "2021-02-10T20:03:43.348556Z",
+    "default_enabled": false,
+    "description": "Show html in a butter bar for certain users",
+    "id": 7168,
+    "initial_value": null,
+    "name": "butter_bar",
+    "project": {
+     "id": 12,
+     "name": "Flagsmith Website"
+    },
+    "type": "CONFIG"
+   },
+   "feature_segment": null,
+   "feature_state_value": "<strong>\nYou are using the develop environment.\n</strong>",
+   "identity": null,
+   "identity_identifier": null
+  },
+  "timestamp": "2021-06-18T07:50:26.595298Z"
+ },
+ "event_type": "FLAG_UPDATED"
+}
+```
+
+### Webhook Signature
+
+When your webhook secret is set, Flagsmith uses it to create a hash signature with each payload. This hash signature is passed with each request under the `X-Flagsmith-Signature` header that you need to validate at your end.
+
+#### Validating Signature
+
+Compute an HMAC with the SHA256 hash function. Use request body (raw utf-8 encoded string) as the message and secret (utf8 encoded) as the Key. Here is one example in Python:
+
+```python
+import hmac
+import hashlib
+
+secret = "my shared secret"
+
+expected_signature = hmac.new(
+    key=secret.encode(),
+    msg=request_body,
+    digestmod=hashlib.sha256,
+).hexdigest()
+
+received_signature = request["headers"]["x-flagsmith-signature"]
+hmac.compare_digest(expected_signature, received_signature) is True
+```
+
 ## Custom fields
 
 Optional or required custom fields can be defined when creating or updating environments.

docs/docs/third-party-integrations/webhook.md

@@ -7,23 +7,24 @@ hide_title: true
 
 ![Webhook](/img/integrations/webhook/webhook-logo.svg)
 
-You can integrate Flagsmith with your own data warehouse using our Webhook integration. The integration automatically
-sends the flag states for identified users as a webhook, to a URL you specify, for cohort analysis, A/B testing and
-more. The process is as follows:
+Identity webhooks allow you to integrate Flagsmith with your own data warehouse or analytics infrastructure. The integration automatically sends flag evaluations for identified users to a URL you specify whenever an identity's flags are evaluated via the `Get Identity Flags` endpoint.
+
+This is particularly useful for:
+- **Analytics processing**: Enriching your analytics data with flag states and segment memberships
+- **Cohort analysis**: Segmenting users based on the flags they saw
+- **A/B testing**: Tracking which variants users received for experiment analysis
+
+The process is as follows:
 
 ## Integration Setup
 
 1. Write an endpoint that accepts the [JSON schema](#webhook-json-schema) defined below.
 2. Add the integration in Flagsmith, providing your URL created in the step above.
 3. You can also provide a Secret which will be [hashed and included in the HTTP header](#webhook-signature). This will
    allow you to verify that the Webhook has come from Flagsmith.
-4. All API calls generated by the Flagsmith SDK to the `Get Identity Flags` endpoint will send the a full set of flag
+4. All API calls generated by the Flagsmith SDK to the `Get Identity Flags` endpoint will send a full set of flag
    evaluations, traits and segments for that particular user to your webhook URL.
 
-## Audit Log Webhooks {#audit-log-webhooks}
-
-Flagsmith can also send audit log events to your own infrastructure via [Audit Log Web Hooks](/administration-and-security/governance-and-compliance/audit-logs). Configure a webhook endpoint and point your audit log integration at it to receive structured JSON events for all changes in your projects.
-
 ## Webhook JSON Schema
 
 Flagsmith will send a `POST` request to the Webhook url you provide, with the following payload in the body:
@@ -93,6 +94,11 @@ Flagsmith will send a `POST` request to the Webhook url you provide, with the fo
 
 Once the integration has been set up, you can start segmenting your data warehouse users based on the flags that they saw and the segments that they are a member of. This allows you to enrich the data within your warehouse through Flagsmith.
 
+For example, you might use identity webhooks to:
+- Send flag evaluation data to analytics platforms like Amplitude or Mixpanel for cohort analysis
+- Track which A/B test variants users received for experiment analysis
+- Build custom dashboards that correlate flag states with user behaviour
+
 ## Webhook Signature
 
 When your webhook secret is set, Flagsmith uses it to create a hash signature with each payload. This hash signature is