Prometheus Alertmanager

Navi.sh acts as a native Alertmanager webhook receiver. Each alert in the batch is processed individually, and resolved alerts auto-close their corresponding incidents.

POST/v1/events/prometheus/{token}

Setup in Alertmanager

Your integration URL — including the token — is available in the Navi.sh dashboard → Integrations → Prometheus.

Add a webhook_config receiver to your Alertmanager configuration:

# alertmanager.yml
receivers:
  - name: navi-sh
    webhook_configs:
      - url: "https://api.navi.sh/v1/events/prometheus/<token>"
        send_resolved: true   # required for auto-resolve

route:
  receiver: navi-sh
  # Or scope to specific alerts:
  routes:
    - match:
        severity: critical
      receiver: navi-sh

TIP

Set send_resolved: true so Navi.sh can automatically close incidents when alerts recover.

Auto-resolve

Each alert in the alerts[] array is processed independently. An alert with "status": "resolved" closes the incident matched by the alert's fingerprint (or alertname label as a fallback).

Field mapping

Navi.sh incident field	Source
Title	annotations.summary → labels.alertname → "Prometheus Alert"
Description	annotations.description → auto-generated
Severity	labels.severity
Dedup key	fingerprint → labels.alertname

POST /v1/events/prometheus/{token}

Accepts Prometheus Alertmanager webhook payloads. Add this URL as a webhook_config receiver in your Alertmanager configuration.

Processes each alert in the batch individually. Alerts with status: "resolved" auto-resolve incidents via fingerprint matching. Deduplicates by fingerprint or alertname label.

The token is generated in your navi.sh workspace under Integrations.

Payload schema

Field	Type	Description
alerts	array of PrometheusAlert	List of individual alert instances.
commonAnnotations	object<string, string>	Annotations common to all alerts in the group.
commonLabels	object<string, string>	Labels common to all alerts in the group.
groupKey	string	Key identifying this alert group. (example: {}/{}:{alertname="HighCPU"})
groupLabels	object<string, string>	Labels used to group these alerts.
receiver	string	Alertmanager receiver name. (example: navi-sh)
status	string (firing, resolved)	Overall group status. (example: firing)

alerts fields:

Field	Type	Description
annotations	object<string, string>	Alert annotations. Include summary (used as title) and description.
endsAt	string	RFC3339 timestamp when the alert ended. (example: 0001-01-01T00:00:00Z)
fingerprint	string	Unique fingerprint used for deduplication. (example: abc123def456)
generatorURL	string	Link to the Prometheus expression graph. (example: http://prometheus:9090/graph?g0.expr=up%3D%3D0)
labels	object<string, string>	Alert labels. Include alertname and severity.
startsAt	string	RFC3339 timestamp when the alert started firing. (example: 2024-01-15T10:30:00Z)
status	string (firing, resolved)	Alert status for this individual instance. (example: firing)

Examples

Alertmanager Firing

{
  "alerts": [
    {
      "annotations": {
        "description": "CPU above 80% for 5 minutes",
        "summary": "High CPU"
      },
      "fingerprint": "abc123def456",
      "labels": {
        "alertname": "HighCPU",
        "instance": "web-01:9090",
        "severity": "critical"
      },
      "startsAt": "2024-01-15T10:30:00Z",
      "status": "firing"
    }
  ],
  "commonLabels": {
    "alertname": "HighCPU",
    "severity": "critical"
  },
  "groupLabels": {
    "alertname": "HighCPU"
  },
  "receiver": "navi-sh",
  "status": "firing"
}

Response codes

• 202 — Accepted — processing is asynchronous
• 400 — Invalid request body (malformed JSON or wrong content type)
• 401 — Invalid service token
• 402 — Workspace suspended (trial ended or plan lapsed): new alerts are rejected; resolutions are still accepted
• 500 — Unexpected server error