MonoDuty Core Concepts

Core Concepts

A workspace contains teams; a team owns services, and a service owns explicit alert sources. Each source exposes a revocable mndty.com URL. Incoming alerts create team-scoped incidents and enter the configured on-call and escalation workflow.

Services and alert sources

A service is the ownership boundary for an operational system. Create an explicit alert source under that service to receive its Webhook URL. Named/native tool adapters are not implied by the universal HTTP contract.

Public alert ingestion

The generally available public ingestion surface is the service-specific Webhook URL:

There is no separate public Opsgenie-compatible Events API in the current production contract.

Webhook tokens

The token is part of the source URL and grants alert-ingestion access to that source. Keep the full URL out of repositories, screenshots, analytics, and logs. Rotation invalidates the previous URL; update senders and verify the old URL returns 404.

Rate limiting

Public ingestion is rate limited. Treat HTTP 429 as a retryable response, honor Retry-After when present, and use a stable Idempotency-Key on every retry.

Sender behavior

Use bounded exponential backoff with jitter for timeouts, 429, and transient 5xx responses. Do not retry validation errors until the payload is corrected.

Protecting the route

Keep payloads small, avoid retry storms, and alert on sustained rejection or latency. Rate limits may change operationally, so clients must respond to HTTP status and headers rather than hard-coded guesses.

Idempotent ingestion

Send an Idempotency-Key header of at most 191 characters. The dedup_key JSON field is a fallback when the header is absent.

• First key and payload: HTTP 202, duplicate: false.
• Same key and canonically identical payload: HTTP 200, the original incident, duplicate: true.
• Same key with a different payload: HTTP 409, code idempotency_conflict.

Retries do not update incidents

Idempotency protects one create request from duplicate delivery. A replay never edits the active incident. To represent a different event, use a new key; acknowledge and resolve incidents through the authenticated incident endpoints.