Generic Webhook

The generic webhook endpoint accepts any JSON payload and maps it to a Navi.sh incident using a canonical field vocabulary. Use this when your monitoring tool supports custom webhooks but doesn't appear in the native integrations list.

Endpoint: POST /api/v1/events/webhook/{token}

---

Payload schema

All fields are optional. Navi.sh applies aliasing and sensible defaults when fields are absent. Any extra JSON keys not in the list below are captured in an incident custom bag.

Field	Type	Description
title	string	Alert title. Also accepted as subject.
description	string	Alert description. Also accepted as message.
severity	string	Severity level. Also accepted as priority. One of: critical, error, warning, info.
type	string	Alert type. Defaults to "webhook".
dedup_key	string	Deduplication key. Alerts with the same key are correlated into one incident. Required for resolution.
status	string	Set to "resolved" (with dedup_key) to auto-resolve an open incident.
link	string	Reference link to the alert in the source system.
hostname	string	Source host that generated the alert.
region	string	Geographic or logical region.
labels	object	Arbitrary key: value metadata.
annotations	object	Additional annotations.
values	object	Metric values.
starts_at	string (RFC3339)	Timestamp when the alert started.
ends_at	string (RFC3339)	Timestamp when the alert ended.

---

Examples

Fire an alert

curl -X POST "https://api.navi.sh/api/v1/events/webhook/<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "High CPU Usage",
    "description": "CPU usage exceeded 90% for 5 minutes",
    "severity": "critical",
    "dedup_key": "cpu-alert-prod-1",
    "status": "firing",
    "hostname": "web-01.prod",
    "starts_at": "2024-01-15T10:30:00Z",
    "labels": {
      "env": "production",
      "service": "api"
    }
  }'

Resolve an alert

Send the same dedup_key with "status": "resolved" to automatically close the incident:

curl -X POST "https://api.navi.sh/api/v1/events/webhook/<token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "dedup_key": "cpu-alert-prod-1"
  }'

---

Field aliasing

If you can't rename fields in your tool's webhook template, these aliases are supported:

Canonical	Alias
title	subject
description	message
severity	priority

---

Response

202 Accepted — the payload was queued for processing.