add webhook docs (#444)

docs/documentation/configuration/overview.md

@@ -669,7 +669,7 @@ The webhook section allows you to configure a webhook that is called on certain
 A JSON object is sent in a POST request to the webhook URL with the following structure:
 ```json
 {
-  "event": "peer_created",
+  "event": "update",
   "entity": "peer",
   "identifier": "the-peer-identifier",
   "payload": {
@@ -679,6 +679,8 @@ A JSON object is sent in a POST request to the webhook URL with the following st
 }
 ```
 
+Further details can be found in the [usage documentation](../usage/webhooks.md).
+
 ### `url`
 - **Default:** *(empty)*
 - **Description:** The POST endpoint to which the webhook is sent. The URL must be reachable from the WireGuard Portal server. If the URL is empty, the webhook is disabled.

docs/documentation/usage/webhooks.md

@@ -0,0 +1,86 @@
+
+Webhooks allow WireGuard Portal to notify external services about events such as user creation, device changes, or configuration updates. This enables integration with other systems and automation workflows.
+
+When webhooks are configured and a specified event occurs, WireGuard Portal sends an HTTP **POST** request to the configured webhook URL. 
+The payload contains event-specific data in JSON format.
+
+## Configuration
+
+All available configuration options for webhooks can be found in the [configuration overview](../configuration/overview.md#webhook).
+
+A basic webhook configuration looks like this:
+
+```yaml
+webhook:
+  url: https://your-service.example.com/webhook
+```
+
+### Security
+
+Webhooks can be secured by using a shared secret. This secret is included in the `Authorization` header of the webhook request, allowing your service to verify the authenticity of the request.
+You can set the shared secret in the webhook configuration:
+
+```yaml
+webhook:
+  url: https://your-service.example.com/webhook
+  secret: "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
+```
+
+You should also make sure that your webhook endpoint is secured with HTTPS to prevent eavesdropping and tampering.
+
+## Available Events
+
+WireGuard Portal supports various events that can trigger webhooks. The following events are available:
+
+- `create`: Triggered when a new entity is created.
+- `update`: Triggered when an existing entity is updated.
+- `delete`: Triggered when an entity is deleted.
+- `connect`: Triggered when a user connects to the VPN.
+- `disconnect`: Triggered when a user disconnects from the VPN.
+
+The following entity types can trigger webhooks:
+
+- `user`: When a WireGuard Portal user is created, updated, or deleted.
+- `peer`: When a peer is created, updated, or deleted. This entity can also trigger `connect` and `disconnect` events.
+- `interface`: When a device is created, updated, or deleted.
+
+## Payload Structure
+
+All webhook events send a JSON payload containing relevant data. The structure of the payload depends on the event type and entity involved.
+A common shell structure for webhook payloads is as follows:
+
+```json
+{
+  "event": "create",
+  "entity": "user",
+  "identifier": "the-user-identifier",
+  "payload": {
+    // The payload of the event, e.g. peer data.
+    // Check the API documentation for the exact structure.
+  }
+}
+```
+
+
+### Example Payload
+
+The following payload is an example of a webhook event when a peer connects to the VPN:
+
+```json
+{
+  "event": "connect",
+  "entity": "peer",
+  "identifier": "Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=",
+  "payload": {
+    "PeerId": "Fb5TaziAs1WrPBjC/MFbWsIelVXvi0hDKZ3YQM9wmU8=",
+    "IsConnected": true,
+    "IsPingable": false,
+    "LastPing": null,
+    "BytesReceived": 1860,
+    "BytesTransmitted": 10824,
+    "LastHandshake": "2025-06-26T23:04:33.325216659+02:00",
+    "Endpoint": "10.55.66.77:33874",
+    "LastSessionStart": "2025-06-26T22:50:40.10221606+02:00"
+  }
+}
+```

mkdocs.yml

@@ -82,6 +82,7 @@ nav:
           - General: documentation/usage/general.md
           - LDAP: documentation/usage/ldap.md
           - Security: documentation/usage/security.md
+          - Webhooks: documentation/usage/webhooks.md
           - REST API: documentation/rest-api/api-doc.md
       - Upgrade: documentation/upgrade/v1.md
       - Monitoring: documentation/monitoring/prometheus.md