Integrations

Diese Seite beschreibt die Chat-Kanäle Microsoft Teams (Bot Framework) und Cisco Webex sowie die ausgehenden Webhooks. Die E-Mail-Anbindung hat eine eigene Seite: E-Mail-System für den Weg einer Mail und Inbound Mailboxes API für die Verwaltung der Postfächer.

Wie Benachrichtigungen modelliert, konfiguriert und ausgeliefert werden (Notification-Typen, Kanäle, Global-/User-Einstellungen, Templates, Quiet Hours, Push, In-App, .ics), ist auf einer eigenen Seite beschrieben: Notification-System. Diese Seite behandelt die externen Integrationen und die Kanal-Anbindung.

🔗

Funktionen

✓ Microsoft Teams per Bot Framework (DM + Channel)

✓ Adaptive Cards mit eigenen Farben

✓ Cisco Webex (Markdown-Direktnachrichten)

✓ Ausgehende Webhooks mit SSRF-Schutz

✓ Zugangsdaten verschlüsselt gespeichert

✓ Fünf Benachrichtigungs-Kanäle nebeneinander

Benachrichtigungs-Kanäle

Eviworx liefert Benachrichtigungen über fünf Kanäle: IN_APP, E-Mail, Push, Microsoft Teams und Cisco Webex. Die Anbindung von Teams und Webex ist unten beschrieben; das vollständige Notification-Modell (Typen, Templates, Global-/User-Einstellungen, Quiet Hours, Digest) steht unter Notification-System.

Microsoft Teams Integration (Bot Framework)

🤖 Teams über das Bot Framework

Die Teams-Integration nutzt das Microsoft Bot Framework. Damit sind Direktnachrichten an einzelne Benutzer, Channel-Posts, Adaptive Cards, OAuth2-Authentifizierung und Kommunikation in beide Richtungen möglich.

Teams Bot Framework Konfiguration

// Teams Settings (Bot Framework)
interface TeamsSettings {
  id: string;
  isEnabled: boolean;
  appId: string | null;        // Bot App ID (Azure AD)
  appPassword: string | null;  // Bot App Password (client secret)
  tenantId: string | null;     // Azure AD Tenant ID (or 'botframework.com')
}

Retry: Scheitert die Zustellung an Teams oder Webex an einem vorübergehenden Fehler (5xx, 429, Netzwerk, Timeout), wird sie automatisch wiederholt: bis zu 6 Versuche mit exponentiell wachsendem Abstand, beginnend bei 15 Sekunden.

🔒 SSRF Protection: serviceUrl-Domains werden validiert. Erlaubt sind nur: smba.trafficmanager.net, botframework.com, teams.microsoft.com. Alle URLs müssen HTTPS verwenden.

Bot Framework Auth & Token Management

Eviworx meldet sich per OAuth2 Client Credentials beim Bot Framework an (Token-Endpoint https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token, Scope https://api.botframework.com/.default). Tokens werden zwischengespeichert und fünf Minuten vor Ablauf automatisch erneuert; lehnt das Bot Framework ein Token ab, wird ein neues angefordert.

Teams Adaptive Card Format

// TeamsAdapter sends Adaptive Cards via Bot Framework REST API:
// POST {serviceUrl}/v3/conversations/{conversationId}/activities

{
  "type": "message",
  "attachments": [{
    "contentType": "application/vnd.microsoft.card.adaptive",
    "content": {
      "type": "AdaptiveCard",
      "version": "1.4",
      "body": [
        {
          "type": "TextBlock",
          "text": "Ticket Assigned",
          "weight": "Bolder",
          "size": "Medium",
          "color": "Accent"
        },
        {
          "type": "TextBlock",
          "text": "For: John Doe",
          "size": "Small",
          "isSubtle": true
        },
        {
          "type": "TextBlock",
          "text": "**Ticket TK-000123** has been assigned to you.\n\nPriority: HIGH",
          "wrap": true
        }
      ],
      "actions": [{
        "type": "Action.OpenUrl",
        "title": "Details anzeigen",
        "url": "https://helpdesk.com/tickets/123"
      }]
    }
  }]
}

Teams Delivery: DM vs. Channel

Modus	Trigger	Voraussetzung
DM	`recipientEmail`	User muss Bot installiert haben (conversation reference gespeichert)
Channel	`metadata.teamsChannelId`	Bot muss dem Channel hinzugefügt sein (channel reference gespeichert)

Teams Theme Colors

Event-Type	Farbe	Hex
SLA_BREACH, CHANGE_REJECTED	Rot	`D13438`
SLA_WARNING	Gelb	`FFB900`
TICKET_RESOLVED, CHANGE_APPROVED	Grün	`107C10`
Default (alle anderen)	Blau	`0078D4`

Cisco Webex Integration

Webex Konfiguration

// Settings Key: 'webex-settings'
{
  "botToken": "Bearer_YOUR_BOT_TOKEN_HERE",  // AES-256-GCM at-rest
  "isEnabled": true
}

Das Webex-botToken und das Teams-appPassword werden mit AES-256-GCM verschlüsselt gespeichert und in GET-Responses nie ausgegeben (nur als _hasToken- bzw. _hasBotConfig-Flag). Details auf der Sicherheits-Seite.

🤖 Bot Setup: Erstelle einen Webex Bot unter developer.webex.com. Der Bot-Token wird benötigt für API-Zugriff.

Webex Message Format

// POST to https://webexapis.com/v1/messages
{
  "toPersonEmail": "user@example.com",
  "markdown": "**Ticket TK-000123** has been assigned to you.\n\n**Title:** Database connection timeout\n**Priority:** HIGH\n\n[View Ticket](https://helpdesk.com/tickets/123)"
}

// Response:
{
  "id": "message-id-uuid",
  "roomId": "room-id",
  "toPersonEmail": "user@example.com",
  "text": "Ticket TK-000123 has been assigned to you...",
  "markdown": "**Ticket TK-000123**...",
  "created": "2026-01-28T10:00:00.000Z"
}

Webex vs. Teams Vergleich

Feature	Microsoft Teams	Cisco Webex
Delivery-Methode	Bot Framework (proactive messaging)	Bot API (outgoing)
Card-Format	Adaptive Cards v1.4	Native Markdown
Targeting	DM (Person) + Channel	Person-to-Person (E-Mail)
Interactive Buttons	✅ Action.OpenUrl	❌ Nur Links
Auth-Methode	OAuth2 Client Credentials	Bot Token (Bearer)
Setup-Aufwand	Mittel (Azure App Registration + Bot)	Einfach (Bot-Token)

Ausgehende Webhooks

Ausgehende Webhooks werden als CronJob-Action webhook, als Workflow-Schritt „Automated Action“ oder als Aktion einer SLA-Eskalation konfiguriert. Alle drei nutzen denselben Ausführungsweg.

// Webhook call (configurable fields)
{
  "url": "https://hooks.example.com/services/...",
  "method": "POST",              // GET | POST | PUT | PATCH | DELETE (default POST)
  "headers": { "X-Custom-Header": "value" },
  "payload": { "ticket": "HD-000123" },   // sent as JSON body (not for GET)
  "timeoutMs": 15000             // 1000–30000 (default 15000)
}

// Headers sent with every call:
Content-Type: application/json
User-Agent: Eviworx-Webhook/1.0
// Host, Content-Length, Transfer-Encoding, Connection and Upgrade
// cannot be overridden; redirects are not followed.

Konfiguration im Detail: CronJobs API → · Workflows API →

SSRF Protection

Webhook-URLs werden beim Speichern und bei jedem Aufruf geprüft, einschließlich DNS-Auflösung gegen DNS-Rebinding. Es gelten dieselben Regeln wie für alle ausgehenden Verbindungen:

✅ Erlaubt: http und https; Standard-Ports 80, 443, 8080, 8443 (anpassbar über SSRF_ALLOWED_PORTS)
❌ Hart blockiert (nie freigebbar): localhost, 127.0.0.1, ::1, 0.0.0.0, Metadata 169.254.x + Cloud-Metadata-Hostnamen, Link-Local fe80::, ff00::
❌ Private Netze (10.x, 172.16.x, 192.168.x, fc00::/fd00::) per Default blockiert — bei Bedarf via SSRF_ALLOWLIST freigebbar

🔒 Details zum SSRF-Schutz: Security →.

Deployment & Configuration

Docker Services

Service	Beschreibung	Key Features
`notification-worker`	Notification Dispatch	Multi-Channel Routing (EMAIL, TEAMS Bot Framework, WEBEX), Attachments
`backend`	Main Application	Benachrichtigungs-Dispatch, Kanal-Einstellungen, Webhook-Aufrufe
`redis`	Queues, Pub/Sub & Locks	Pub/Sub, BullMQ, Rate-Limiting, Distributed Locks

Environment Variables

# ============================================
# Notification Worker
# ============================================

# Redis (with password!)
REDIS_URL=redis://:PASSWORD@redis:6379
REDIS_PASSWORD=PASSWORD

# Backend API
BACKEND_URL=http://backend:3000
INTERNAL_API_KEY=your-internal-api-key

# Worker
NOTIFICATION_WORKER_CONCURRENCY=5
LOG_LEVEL=info

# ============================================
# Backend
# ============================================

# Frontend URL for link generation
FRONTEND_URL=https://helpdesk.company.com

# ============================================
# Redis
# ============================================
# All services use authenticated Redis URLs:
# redis://:PASSWORD@redis:6379

Die Zugangsdaten von Teams und Webex liegen nicht in Umgebungsvariablen, sondern verschlüsselt in den Einstellungen. Die vollständige Liste aller Variablen steht unter Environment.

🔐 Redis-Passwort: Alle REDIS_URL-Einträge enthalten ein Passwort im Format redis://:PASSWORD@redis:6379. Das Passwort wird via REDIS_PASSWORD Environment-Variable konfiguriert.

Best Practices

Teams-Setup: Azure App Registration erstellen, Bot Channel Registration, App installieren lassen. Conversation References werden automatisch gespeichert.
Webex-Setup: Bot erstellen, Token in Settings, Health-Check regelmäßig prüfen
Webhooks: Ziel-URLs möglichst per HTTPS; private Netze nur gezielt über SSRF_ALLOWLIST freigeben
Kanal-Ausfall: Fällt ein Chat-Kanal aus, bleiben E-Mail und die Anzeige in der Anwendung als Wege bestehen — deshalb sollte nie ein einzelner Kanal der einzige für dringende Benachrichtigungen sein.