MonoDuty Core Concepts

Core Concepts

Webhooks

A webhook is a unique URL endpoint that accepts HTTP POST requests. When a request is received, MonoDuty processes the payload and sends alerts to your configured notification channels.

Notification Channels

MonoDuty supports multiple notification channels:

• SMS - Text messages with global delivery
• Email - Rich HTML emails with full context
• Voice Calls - Automated phone calls for critical alerts
• Push Notifications - Mobile app notifications (iOS & Android)

Severity Levels

Services & Events API

Services are the core building blocks in MonoDuty. Each service represents a system, application, or component you want to monitor. Services receive events through a unique integration key and route alerts to the right people through configured notification channels.

Key Features

• Integration Keys — Each service gets a unique key for sending events
• OpsGenie-Compatible — Natively understands OpsGenie Alert API v2 format
• Priority Mapping — P1-P5 priority levels with automatic severity mapping
• Deduplication — Use aliases to prevent duplicate alerts
• Multi-Channel Routing — Route alerts to Email, SMS, Voice, Slack, Discord, Push
• Escalation Policies — Configure time-based escalation chains
• Auto-Incidents — Automatically create and manage incidents from events

Sending Events

The Events API is the primary way to send alerts to a service. Send a POST request with your integration key:

Basic Event Example

curl -X POST 'https://api.monoduty.com/api/v1/events?integration_key=YOUR_INTEGRATION_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "CPU usage exceeded 90% on prod-server-01",
    "priority": "P2",
    "alias": "cpu-alert-prod-001",
    "description": "CPU has been above 90% for 5 minutes",
    "tags": ["production", "cpu", "server"],
    "entity": "prod-server-01",
    "source": "prometheus"
  }'

Event Fields

Priority Levels

Integration Keys

Each service has a unique integration key used to authenticate events. You can find your integration key in the service detail page.

Getting Your Integration Key

1. Navigate to Dashboard → Services
2. Click on a service (or create a new one)
3. Copy the Integration Key from the service detail page
4. Use this key as a query parameter: ?integration_key=YOUR_KEY

Rate Limiting

MonoDuty applies rate limiting at multiple layers to protect the platform and ensure fair usage across all accounts. Rate limits prevent abuse, control costs, and maintain service reliability for everyone.

Rate Limit Layers

MonoDuty enforces rate limits at three distinct layers:

429 Response Format

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later.",
  "retryAfter": 900,
  "requestId": "req_abc123"
}

Endpoint Rate Limits

Each API endpoint category has its own rate limit window and maximum request count. Requests to health checks, static assets, and internal IPs (in development) are automatically excluded.

Webhook Rate Limits

Webhook ingestion endpoints have an additional feature: successful requests are not counted against the limit. This means the 300/5min limit only applies to failed or malformed requests, so legitimate webhook traffic is rarely affected.

Advanced Authentication Rate Limiting

Login and authentication endpoints have an additional layer of protection that combines IP-based and user-based rate limiting to prevent brute-force attacks.

Both dimensions are checked simultaneously. If either limit is exceeded, the request is rejected with a 429 response.

How It Works

Request arrives at /login
  ├── Check IP limit (50/hour)
  │   └── Exceeded? → 429 "Too many login attempts from this IP"
  ├── Check Username limit (10/hour)
  │   └── Exceeded? → 429 "Too many login attempts for this account"
  └── Both passed → Continue to authentication

Plan-Based Webhook Limits

In addition to endpoint rate limits, webhook ingestion is also subject to your subscription plan limits. Each plan defines how many webhook requests you can send per hour:

Deduplication

MonoDuty automatically deduplicates incoming events and alerts to prevent duplicate incidents from flooding your team. When multiple identical alerts arrive (e.g., a monitoring tool firing repeatedly for the same issue), MonoDuty groups them into a single incident and tracks occurrence count.

How It Works

MonoDuty uses a two-phase deduplication strategy:

Incoming Event
  │
  ├── Phase 1: Exact Match
  │   └── Is there an OPEN incident with the same
  │       external_incident_id + service_id?
  │       ├── YES → Update existing incident (increment occurrence count)
  │       └── NO  → Continue to Phase 2
  │
  ├── Phase 2: Semantic Match (if AI enabled)
  │   └── Are there OPEN incidents with semantically
  │       similar title/description?
  │       ├── YES (similarity ≥ 85%) → Update existing incident
  │       └── NO  → Create new incident
  │
  └── No Match → Create new incident

Exact Match Deduplication

The primary deduplication method uses exact matching on two fields:

• external_incident_id — A unique identifier from your monitoring tool (e.g., Sentry issue ID, Prometheus alert fingerprint)
• service_id — The MonoDuty service receiving the event

If an OPEN or IN_PROGRESS incident already exists with the same combination, MonoDuty updates the existing incident instead of creating a new one:

• Increments the occurrence_count
• Updates last_seen_at timestamp
• Appends the new occurrence to the incident's metadata history (last 10 kept)

Events API Deduplication

When using the Events API, the alias field serves as the deduplication key:

{
  "message": "CPU usage above 90% on prod-server-01",
  "priority": "P2",
  "alias": "cpu-alert-prod-001",
  "source": "prometheus"
}

If you send another event with the same alias to the same service while the original incident is still open, MonoDuty will update the existing incident rather than creating a duplicate.

Safe Defaults

MonoDuty's dedup engine is designed with a fail-safe approach:

• If no alias or external_incident_id is provided, a new incident is always created
• If the deduplication check fails (e.g., database error), a new incident is created rather than silently dropping the alert
• The rationale: a duplicate incident is less risky than a lost incident

Semantic Deduplication (AI-Powered)

When exact matching doesn't find a duplicate (e.g., the alert doesn't include an alias), MonoDuty can optionally use AI-powered semantic similarity to detect incidents that describe the same underlying problem in different words.

How Semantic Matching Works

1. MonoDuty generates an AI embedding (vector representation) of the new incident's title and description
2. It compares this embedding against recent open incidents within the same service and group
3. If the cosine similarity between any existing incident and the new event exceeds the threshold (default: 85%), the events are considered duplicates
4. The existing incident is updated with the new occurrence data

Configuration

Example: Semantic Match

These two alerts would be matched as duplicates by the semantic engine, even though the wording differs:

Alert 1: "Database connection pool exhausted on prod-db-01"
Alert 2: "MySQL connection limit reached — prod-db-01 cannot accept new connections"

Cosine Similarity: 0.91 (above 0.85 threshold) → DUPLICATE

Combined Deduplication Flow

MonoDuty always tries exact match first (fastest), then falls back to semantic matching: