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.

POST/v1/events/webhook/{token}

Quick start

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

Fire an alert

curl -X POST "https://api.navi.sh/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/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

All fields are optional. Navi.sh applies aliasing and sensible defaults when fields are absent. Any unrecognized JSON keys are captured in the incident's custom bag.

POST /v1/events/webhook/{token}

Accepts any JSON payload and maps it to a navi.sh incident using the canonical field vocabulary. Unknown fields are captured in a custom bag and forwarded to the incident details.

Set "status": "resolved" (together with a dedup_key) to auto-resolve a previously fired incident.

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

Payload schema

Field	Type	Description
annotations	object<string, string>	Additional annotations attached to the alert.
dedup_key	string	Deduplication key. Alerts with the same key are correlated into one incident. Required when resolving. (example: disk-web-01)
description	string	Alert description. Also accepted as message. (example: Disk /dev/sda1 at 92% on host web-01)
ends_at	string	RFC3339 timestamp of when the alert ended. (example: 2024-01-15T11:00:00Z)
hostname	string	Source host that generated the alert. (example: web-01.us-east-1)
labels	object<string, string>	Arbitrary key-value metadata labels.
link	string	Reference link to the alert in the source system. (example: https://monitoring.example.com/alerts/42)
message	string	Alias for description. (example: Disk /dev/sda1 at 92%)
priority	string (critical, error, warning, info)	Alias for severity. (example: critical)
region	string	Geographic or logical region. (example: us-east-1)
severity	string (critical, error, warning, info)	Severity level. Also accepted as priority. (example: critical)
starts_at	string	RFC3339 timestamp of when the alert started firing. (example: 2024-01-15T10:30:00Z)
status	string (firing, resolved)	Set to "resolved" (with dedup_key) to auto-resolve an open incident. (example: firing)
subject	string	Alias for title. (example: High disk usage)
title	string	Alert title. Also accepted as subject. (example: Disk usage > 90%)
type	string	Alert type. Defaults to "webhook". (example: alert)
values	object<string, string>	Metric values associated with the alert.

Examples

Firing

{
  "dedup_key": "cpu-alert-prod-1",
  "description": "CPU usage exceeded 90% for 5 minutes",
  "hostname": "web-01.prod",
  "labels": {
    "env": "production",
    "service": "api"
  },
  "severity": "critical",
  "starts_at": "2024-01-15T10:30:00Z",
  "status": "firing",
  "title": "High CPU Usage"
}

Resolved

{
  "dedup_key": "cpu-alert-prod-1",
  "status": "resolved"
}

Response codes

• 202 — Accepted — processing is asynchronous
• 401 — Invalid service token
• 500 — Unexpected server error