Overview

Waggles is STING’s cross-platform notification dispatcher. Named after the waggle dance that bees use to communicate vital information to their hive, Waggles routes platform events (report completions, PII alerts, system health changes, escalations) to all connected communication channels.

Waggles lives inside the public_bee microservice and leverages the existing connector framework for multi-platform delivery.

Event Types

Event TypeSeverityDescription
report.completedinfoReport generation finished successfully
report.failedwarningReport generation failed
pii.detectedwarningPII found during content scan
pii.compliance_alertcriticalCompliance framework violation detected
system.maintenanceinfoMaintenance mode enabled/disabled
system.health_degradedcriticalOne or more services unhealthy
system.backup_completedinfoSystem backup finished
conversation.escalatedwarningChat conversation escalated by user or bot
conversation.handoffwarningBot requests human agent handoff
user.admin_actioninfoAdmin created, deleted, or modified a user
knowledge.upload_completeinfoHoney Jar document upload finished
knowledge.index_readyinfoKnowledge base indexing completed
security.auth_failurewarningAuthentication failure detected
customvariesCustom event from integrations

Architecture

┌──────────────────────────────────────────────┐
│              Event Sources                    │
│  App Service  │  Knowledge  │  External AI   │
└───────┬───────┴──────┬──────┴───────┬────────┘
        │              │              │
        ▼              ▼              ▼
┌──────────────────────────────────────────────┐
│           Waggles Dispatcher                  │
│                                               │
│  1. Receive event (HTTP POST or Redis)        │
│  2. Resolve targets (subscription rules)      │
│  3. Filter by severity                        │
│  4. Render platform-specific templates        │
│  5. Deliver via connector send_response()     │
│  6. Record delivery result in history         │
└──────────────────────────────────────────────┘
        │              │              │
        ▼              ▼              ▼
┌──────────┐   ┌──────────┐   ┌──────────┐
│  Slack   │   │  Teams   │   │ Discord  │
│ Channel  │   │ Channel  │   │ Channel  │
└──────────┘   └──────────┘   └──────────┘

Subscriptions

Subscriptions define which events go to which platforms and channels. Each subscription has:

  • Event type — Which event to match (or * for all)
  • Platform — Target platform (slack, teams, discord, or * for all)
  • Channel ID — Specific channel to deliver to
  • Severity filter — Minimum severity level (info, warning, critical)
  • Enabled — Toggle without deleting

Default Subscriptions

When Waggles initializes, three default subscriptions are created:

  1. Critical alerts — All critical events → all connected platforms
  2. PII alerts — All pii.* events → all connected platforms
  3. Escalations — All conversation.escalated events → all connected platforms

Managing Subscriptions

Via the admin panel: Admin → Waggles

Or via API:

# List subscriptions
curl -sk -H "X-API-Key: $API_KEY" \
  https://your-sting/api/public-bee/api/waggles/subscriptions

# Create a subscription
curl -sk -X POST -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "report.completed",
    "platform": "slack",
    "channel_id": "C0123456789",
    "severity_filter": "info",
    "enabled": true
  }' \
  https://your-sting/api/public-bee/api/waggles/subscriptions

# Delete a subscription
curl -sk -X DELETE -H "X-API-Key: $API_KEY" \
  https://your-sting/api/public-bee/api/waggles/subscriptions/{id}

Templates

Waggles renders notifications with platform-aware templates:

  • Slack — Block Kit formatting with severity-colored sidebars
  • Teams — Adaptive Card format with themed sections
  • Discord — Embed format with severity-colored borders
  • Fallback — Plain text for unsupported platforms or webhook targets

Each event type has a dedicated renderer that includes relevant payload data (report name, PII types found, affected services, etc.).

API Reference

All endpoints are under /api/public-bee/api/waggles/ and require service API key authentication.

MethodEndpointDescription
POST/dispatchEmit a waggle event (service-to-service)
GET/subscriptionsList active subscriptions
POST/subscriptionsCreate a subscription
DELETE/subscriptions/{id}Remove a subscription
GET/historyRecent delivery history
GET/event-typesList all supported event types
POST/testSend a test notification

Emitting Events from Services

Other STING services emit events to Waggles using a lightweight HTTP client:

Flask App Service

from services.waggles_client import waggles

# Fire-and-forget — won't block if public_bee is down
waggles.emit(
    event_type="report.completed",
    title="Report Ready",
    message=f"Report '{report_name}' has been generated",
    severity="info",
    payload={"report_id": report_id, "report_name": report_name}
)

FastAPI Services (knowledge_service, etc.)

import httpx

async def emit_waggles_event(event_type, title, message, **kwargs):
    try:
        async with httpx.AsyncClient() as client:
            await client.post(
                f"{PUBLIC_BEE_URL}/api/waggles/dispatch",
                json={"event_type": event_type, "title": title, "message": message, **kwargs},
                headers={"X-API-Key": API_KEY},
                timeout=5.0
            )
    except Exception:
        pass  # Best-effort — notifications are non-critical

Admin UI

The Waggles page in the admin panel provides:

  • Subscription management — Create, edit, enable/disable, delete rules
  • Delivery history — View recent notifications with status (delivered/failed)
  • Event types reference — Browse all supported event types with descriptions
  • Test notifications — Send a test event to verify connectivity
  • Stats overview — Active rules count, delivered/failed totals

Last updated: