Integrations

This page describes the chat channels Microsoft Teams (Bot Framework) and Cisco Webex as well as outgoing webhooks. The email connection has its own pages: Email System for the path of a mail and Inbound Mailboxes API for managing the mailboxes.

How notifications are modelled, configured and delivered (notification types, channels, global/user settings, templates, quiet hours, push, in-app, .ics) is documented on its own page: Notification System. This page covers the external integrations and channel connectivity.

🔗

Features

✓ Microsoft Teams via Bot Framework (DM + channel)

✓ Adaptive cards with your own colours

✓ Cisco Webex (Markdown direct messages)

✓ Outbound webhooks with SSRF protection

✓ Credentials stored encrypted

✓ Five notification channels side by side

Notification Channels

Eviworx delivers notifications across five channels: IN_APP, email, push, Microsoft Teams and Cisco Webex. The Teams and Webex connection is described below; the full notification model (types, templates, global/user settings, quiet hours, digest) is documented under Notification System.

Microsoft Teams Integration (Bot Framework)

🤖 Teams via the Bot Framework

The Teams integration uses the Microsoft Bot Framework. This enables direct messages to individual users, channel posts, Adaptive Cards, OAuth2 authentication and two-way communication.

Teams Bot Framework Configuration

// 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: If delivery to Teams or Webex fails with a transient error (5xx, 429, network, timeout), it is retried automatically: up to 6 attempts with exponentially increasing delay, starting at 15 seconds.

🔒 SSRF Protection: serviceUrl domains are validated. Only allowed: smba.trafficmanager.net, botframework.com, teams.microsoft.com. All URLs must use HTTPS.

Bot Framework Auth & Token Management

Eviworx authenticates with the Bot Framework via OAuth2 client credentials (token endpoint https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token, scope https://api.botframework.com/.default). Tokens are cached and renewed automatically five minutes before they expire; if the Bot Framework rejects a token, a new one is requested.

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

Mode	Trigger	Prerequisite
DM	`recipientEmail`	User must have installed the bot (conversation reference stored)
Channel	`metadata.teamsChannelId`	Bot must be added to channel (channel reference stored)

Teams Theme Colors

Event Type	Color	Hex
SLA_BREACH, CHANGE_REJECTED	Red	`D13438`
SLA_WARNING	Yellow	`FFB900`
TICKET_RESOLVED, CHANGE_APPROVED	Green	`107C10`
Default (all others)	Blue	`0078D4`

Cisco Webex Integration

Webex Configuration

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

The Webex botToken and the Teams appPassword are stored encrypted with AES-256-GCM and never returned in GET responses (only as _hasToken or _hasBotConfig flag). Details on the security page.

🤖 Bot Setup: Create a Webex Bot at developer.webex.com. The bot token is required for API access.

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 Comparison

Feature	Microsoft Teams	Cisco Webex
Delivery Method	Bot Framework (proactive messaging)	Bot API (outgoing)
Card Format	Adaptive Cards v1.4	Native Markdown
Targeting	DM (person) + Channel	Person-to-person (email)
Interactive Buttons	✅ Action.OpenUrl	❌ Links only
Auth Method	OAuth2 Client Credentials	Bot Token (Bearer)
Setup Effort	Medium (Azure App Registration + Bot)	Simple (bot token)

Outbound Webhooks

Outbound webhooks are configured as the CronJob action webhook, as the workflow step "Automated Action" or as an action of an SLA escalation. All three use the same execution path.

// 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.

Configuration details: CronJobs API → · Workflows API →

SSRF Protection

Webhook URLs are checked on save and on every call, including DNS resolution against DNS rebinding. The same rules apply as for all outbound connections:

✅ Allowed: http and https; default ports 80, 443, 8080, 8443 (adjustable via SSRF_ALLOWED_PORTS)
❌ Hard-blocked (never allowlistable): localhost, 127.0.0.1, ::1, 0.0.0.0, metadata 169.254.x + cloud metadata hostnames, link-local fe80::, ff00::
❌ Private nets (10.x, 172.16.x, 192.168.x, fc00::/fd00::) blocked by default — allowlistable via SSRF_ALLOWLIST if needed

🔒 Details on SSRF protection: Security →.

Deployment & Configuration

Docker Services

Service	Description	Key Features
`notification-worker`	Notification dispatch	Multi-channel routing (EMAIL, TEAMS Bot Framework, WEBEX), attachments
`backend`	Main application	Notification dispatch, channel settings, webhook calls
`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

The credentials for Teams and Webex do not live in environment variables but encrypted in the settings. The complete list of all variables is documented under Environment.

🔐 Redis Password: All REDIS_URL entries include a password in the format redis://:PASSWORD@redis:6379. The password is configured via the REDIS_PASSWORD environment variable.

Best Practices

Teams Setup: Create Azure App Registration, Bot Channel Registration, have app installed. Conversation references are saved automatically.
Webex Setup: Create bot, token in settings, check health regularly
Webhooks: Use HTTPS target URLs where possible; allow private networks only selectively via SSRF_ALLOWLIST
Channel outage: If a chat channel fails, email and the in-app display remain as paths — which is why a single channel should never be the only one for urgent notifications.