Skip to main content

Alert Sources

Akritas normalizes every configured monitoring source into one canonical alert contract before deduplication, incident correlation, investigation, or notification. Supported adapters are alertmanager, uptime-kuma, pingdom, and generic.

Configure a source​

Copy the supplied configuration and set the referenced secret:

cp configs/akritas/alerts.example.json configs/akritas/alerts.local.json
export AKRITAS_ALERTMANAGER_TOKEN=example-token

Start Akritas with both the source registry and durable alert store:

./bin/akritas serve \
  -alert-sources-config configs/akritas/alerts.local.json \
  -alert-store data/audit/alerts.jsonl

Each configured source receives a fixed route:

POST /api/v1/alerts/{source}/webhook

The source name selects an operator-configured adapter and authentication policy. It is not accepted from model output or provider data. A source must configure Bearer, HMAC, or secret-header authentication, or explicitly set allow_unauthenticated for a trusted reverse-proxy boundary.

Alertmanager​

Configure Alertmanager to send version 4 payloads to the named source route:

receivers:
  - name: akritas
    webhook_configs:
      - url: http://akritas.example:8090/api/v1/alerts/alertmanager-main/webhook
        send_resolved: true
        http_config:
          authorization:
            type: Bearer
            credentials: example-token

The authenticated legacy route POST /api/v1/alertmanager/webhook remains available for compatibility. New deployments should use the named source route.

Uptime Kuma and Pingdom​

Add a source with type uptime-kuma or pingdom, then point the provider webhook at its named route. Uptime Kuma heartbeat status 0 maps to firing and 1 to resolved. Pingdom DOWN/alert states map to firing, while UP/recovered states map to resolved.

Prefer a provider-native secret header when the provider cannot send a Bearer token or Akritas HMAC. For example:

{
  "name": "uptime-kuma-main",
  "type": "uptime-kuma",
  "secret_header": "X-Webhook-Token",
  "secret_env": "AKRITAS_UPTIME_KUMA_WEBHOOK_TOKEN"
}

Durable processing​

Akritas persists delivery metadata, new canonical events, incident changes, and pending investigation jobs before returning HTTP 202. The in-process worker then runs the normal bounded RAG, skill, planning, and read-only tool workflow. Poll GET /api/v1/investigation-jobs/{id} until the job reaches succeeded or failed, then open its run_id through the Web UI or Run API.

Repeated deduplication keys for the same source return HTTP 200 and do not start another Run. Firing events open or update an incident by correlation key; a resolved event closes it, and a later firing event opens a new incident.

After a successful investigation, Akritas can send the validated result to a generic webhook, Telegram, or Mattermost. See Notifications and Bots.

See the Alert Sources Reference for the exact configuration schema, canonical payload, status codes, and query endpoints.