feat: configure n8n webhooks and update related documentation

2026-05-17 23:01:57 +02:00
parent 387d2ba2ab
commit 44dbf6b93c
4 changed files with 167 additions and 2 deletions
@@ -0,0 +1,152 @@
+# n8n Webhook Routing Configuration
+
+## Overview
+
+n8n is intentionally kept internal to the Docker network and **not exposed to the internet**. To allow the browser to trigger n8n workflows via webhooks, Kong (the API gateway) proxies webhook requests to the internal n8n service.
+
+## Architecture
+
+```
+Browser                Kong (Port 55521)           n8n (Port 5678, internal)
+   |                        |                            |
+   | POST /webhook/*        |                            |
+   |----------------------> | (no strip_path)           |
+   |                        | POST /webhook/*            |
+   |                        |--------------------------> |
+   |                        |    Webhook triggers       |
+   |                        |    workflow               |
+   |<----- Response --------|<---------------------------|
+```
+
+## Configuration Changes
+
+### 1. Kong Configuration (`supabase/kong.yml`)
+
+Added a new service to route webhook traffic to internal n8n:
+
+```yaml
+- name: n8n-webhooks
+  url: http://n8n:5678/
+  routes:
+    - name: n8n-webhooks-all
+      strip_path: false
+      paths:
+        - /webhook/
+  plugins:
+    - name: cors
+```
+
+- `strip_path: false` ensures the full `/webhook/...` path is forwarded to n8n
+- CORS plugin allows browser cross-origin requests (all origins for internal workflow triggers)
+
+### 2. Docker Compose (`docker-compose.yml`)
+
+**Kong service:**
+- Added `n8n` to the `depends_on` list (waits for n8n to start before Kong)
+
+**n8n service:**
+- Updated `WEBHOOK_URL` environment variable to use `${WEBHOOK_DOMAIN:http://localhost:55590}/`
+- This allows production deployments to override the default localhost URL
+
+### 3. Frontend Configuration (`frontend/config.js`)
+
+Updated the webhook URL configuration:
+
+```javascript
+N8N_WEBHOOK_URL: "/webhook/manual-email-send"
+```
+
+This is a **same-origin request** path that works for both:
+- **Local:** `http://localhost:55521/webhook/manual-email-send` (Kong on port 55521)
+- **Production:** `https://your-domain.com/webhook/manual-email-send`
+
+### 4. Admin UI (`frontend/admin.js`)
+
+Updated `sendOrderEmailDirect()` function to use the configured webhook URL directly:
+
+```javascript
+const n8nUrl = window.MCCARS_CONFIG?.N8N_WEBHOOK_URL || "/webhook/manual-email-send";
+```
+
+## Deployment Steps
+
+### For Production Deployment:
+
+1. **Update Kong configuration** by deploying the modified `supabase/kong.yml`
+   - Kong will automatically reload the config and start proxying `/webhook/*` requests
+
+2. **Set environment variables** (in your `.env` file):
+   ```bash
+   # Optional: Override n8n webhook domain (defaults to localhost)
+   WEBHOOK_DOMAIN=https://your-domain.com
+   ```
+   
+   If not set, n8n will use the default `http://localhost:55590/` (only works internally)
+
+3. **Deploy the updated code**:
+   - `frontend/config.js` with the new webhook URL
+   - `frontend/admin.js` with the updated sendOrderEmailDirect function
+   - `docker-compose.yml` with Kong n8n dependency
+   - `supabase/kong.yml` with the new n8n service
+
+4. **Restart the stack**:
+   ```bash
+   docker-compose up -d
+   ```
+
+### For Local Development:
+
+No special configuration needed:
+- Kong is already on port 55521
+- Browser requests to `/webhook/manual-email-send` will be proxied to internal n8n
+- Works the same as production (same-origin requests)
+
+## How It Works
+
+1. **Browser action**: User clicks "Email senden" button in order dialog
+2. **Browser request**: JavaScript POSTs to `/webhook/manual-email-send` (same origin)
+3. **Kong routing**: Kong receives request, forwards to `http://n8n:5678/webhook/manual-email-send`
+4. **n8n webhook**: n8n webhook listener triggers the manual-email-send workflow
+5. **Workflow execution**: n8n fetches order data, builds email, sends via SMTP
+6. **Response**: Workflow returns success/error response to browser
+
+## Security
+
+- **Network isolation**: n8n remains internal, not exposed to internet
+- **No authentication required**: Webhook path is open (can be restricted later if needed)
+- **CORS enabled**: Allows browser requests to Kong
+- **Kong isolation**: Kong is the only service exposed; internal services hidden behind it
+
+## Troubleshooting
+
+### "Failed to fetch" error in browser
+
+1. Check Kong is routing properly:
+   ```bash
+   # Test from inside docker network
+   docker-compose exec kong curl -v http://n8n:5678/webhook/manual-email-send
+   ```
+
+2. Verify Kong config loaded:
+   ```bash
+   docker-compose logs kong | grep "n8n-webhooks"
+   ```
+
+3. Check n8n is running:
+   ```bash
+   docker-compose logs n8n
+   ```
+
+### n8n workflow not triggering
+
+1. Verify webhook path in n8n workflow (should be exactly `/webhook/manual-email-send`)
+2. Check n8n logs for webhook errors:
+   ```bash
+   docker-compose logs n8n | grep webhook
+   ```
+
+## References
+
+- Kong configuration format: https://docs.konghq.com/deck/latest/
+- n8n webhooks: https://docs.n8n.io/nodes/n8n-nodes-base.Webhook/
+- Docker networking: https://docs.docker.com/engine/reference/commandline/network_connect/