Merge pull request #270 from sinamics/webhook

Added webhook feature for organizations.

.vscode/settings.json

@@ -13,5 +13,8 @@
     "editor.codeActionsOnSave": {
         "quickfix.biome": "explicit",
         "source.organizeImports.biome": "explicit"
+    },
+    "[prisma]": {
+        "editor.defaultFormatter": "Prisma.prisma"
     }
 }

docs/docs/Authentication/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Authentication",
+  "position": 2,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/Authentication/oauth.md

@@ -3,7 +3,7 @@ id: oauth
 title: Oauth
 slug: /authentication/oauth/
 description: OAuth Configuration Guide
-sidebar_position: 6
+sidebar_position: 2
 ---
 
 # OAuth Configuration Guide

docs/docs/Basics/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Basics",
+  "position": 7,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/Contribute/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Contribute",
+  "position": 8,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/Licensing Notice/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Licensing Notes",
+  "position": 9,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/Rest Api/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Rest API",
+  "position": 4,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/Showcase/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Showcase",
+  "position": 6,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/Usage/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Configuration & Tools",
+  "position": 5,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/Usage/webhooks.md

@@ -0,0 +1,105 @@
+---
+id: create_webhooks
+title: Webhooks
+slug: /usage/webhooks/
+description: Webhooks are a way for apps to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately.
+sidebar_position: 1
+---
+
+# Configuring Webhooks in ZTNET
+
+Webhooks in ZTNET empower your organization with real-time event notifications. To set up a webhook, you'll need to specify:
+
+- **Webhook Name**: Assign a unique and descriptive name to each webhook.
+- **Webhook Actions**: Choose the [events](#network-events) that should trigger notifications. Multiple selections are allowed.
+- **Endpoint URL (HTTPS)**: This is the receiver URL where ZTNET will send event data. It must be a publicly accessible HTTPS URL to ensure security.
+
+
+## Data Structure
+
+Each webhook event in ZTNET includes a JSON payload sent to the configured endpoint URL. Here are examples of the JSON content for several webhook types:
+
+## Member Configuration Changed (`MEMBER_CONFIG_CHANGED`)
+
+When a member's configuration changes, the webhook will contain the following data:
+
+```json
+{
+  // HookType is the type of hook being fired.
+  "hookType": "MEMBER_CONFIG_CHANGED",
+  // organizationId is the internal ID the hook belongs to
+  "organizationId": "org_123456",
+  // NetworkID is the network the member belongs to
+  "networkId": "network_12345",
+  // MemberID is the network member that was changed
+  "memberId": "mem_112233",
+  // UserID is the ID of the user that modified the network member
+  "userId": "user_445566",
+  // UserEmail is the email address of the user that modified the network member
+  "userEmail": "[email protected]",
+  // Changes is a map of the changes that were made to the network member
+  "changes": {
+    "authorized": true,
+  }
+}
+```
+
+### Network Created (NETWORK_CREATED)
+After a new network is created, the webhook payload will contain the following data:
+```json
+{
+  "hookType": "NETWORK_CREATED",
+  "organizationId": "org_123456",
+  "networkId": "net_78910",
+  "userId": "user_445566",
+  "userEmail": "[email protected]"
+}
+```
+
+## Webhook Events
+
+Webhooks in ZTNET allow you to set up automated notifications for specific events within your networks and organization. Below you'll find the available webhook events and their descriptions:
+
+## Network Events
+
+- **Network Join (`NETWORK_JOIN`)**  
+  Fired when a new member requests to join a network. This event is triggered once when the network controller receives the join request from the member.
+
+- **Network Created (`NETWORK_CREATED`)**  
+  Fired when a network is created within the organization.
+
+- **Network Configuration Changed (`NETWORK_CONFIG_CHANGED`)**  
+  Fired when there is a change in the organization network's configuration settings.
+
+- **Network Deleted (`NETWORK_DELETED`)**  
+  Fired when a network is permanently deleted from the organization.
+
+## Member Events
+
+- **Member Configuration Changed (`MEMBER_CONFIG_CHANGED`)**  
+  Triggered when a member's configuration in a organization network is altered.
+
+- **Member Deleted (`MEMBER_DELETED`)**  
+  Fired when a member is removed from a organization network.
+
+## Organization Events
+
+- **Organization Member Removed (`ORG_MEMBER_REMOVED`)**  
+  Fired when a member is removed from the organization, whether by an administrator or by the member themselves.
+
+
+## Example of Webhook Receiver
+
+To experiment with webhooks or for development purposes, you can use services like [Zapier](https://zapier.com/) to quickly establish a webhook receiver. For instance, to receive an email for each new member request:
+
+1. Set up a "Webhooks by Zapier" trigger, and choose the "Catch Raw Hook" event to capture the raw POST data from ZTNET.
+![zapier triggers](../../images/webhooks/zapier_hook.jpg)
+
+2. Add an "Send Outbound Email" action in Zapier, fill in your email address, and attach the raw POST data as the email content.
+![zapier actions](../../images/webhooks/zapier_actions.jpg)
+
+3. Copy the webhook URL generated by Zapier.
+4. Go to your ZTNET organization's settings, create a new webhook receiver using the copied URL in the `Endpoint URL` field, and select the "NETWORK_JOIN" event type.
+5. Enable your webhook in ZTNET and activate your Zapier workflow.
+
+Now, whenever a new member tries to join your network in ZTNET, you'll receive an email notification through Zapier.

prisma/migrations/20231229104733_webhooks/migration.sql

@@ -0,0 +1,22 @@
+-- CreateTable
+CREATE TABLE "Webhook" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "description" TEXT NOT NULL,
+    "url" TEXT NOT NULL,
+    "enabled" BOOLEAN NOT NULL DEFAULT false,
+    "eventTypes" JSONB NOT NULL,
+    "secret" TEXT DEFAULT '',
+    "lastDelivery" TIMESTAMP(3) DEFAULT CURRENT_TIMESTAMP,
+    "organizationId" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "userId" TEXT,
+
+    CONSTRAINT "Webhook_pkey" PRIMARY KEY ("id")
+);
+
+-- AddForeignKey
+ALTER TABLE "Webhook" ADD CONSTRAINT "Webhook_organizationId_fkey" FOREIGN KEY ("organizationId") REFERENCES "Organization"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Webhook" ADD CONSTRAINT "Webhook_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;