Connect your monitoring

Supported inbound sources#

Source	Integration kind	Operator responsibility
Prometheus Alertmanager	alertmanager	Point a webhook_configs receiver at the integration URL; firing and resolved alerts are both handled. Grafana unified alerting, Mimir, Thanos Ruler, Cortex and vmalert send the same payload shape.
Icinga 2	icinga	A notification command posts host, service, state, type, output, severity and timestamp; recovery clears. Provide stable condition identity and consistent state/recovery timestamps.
Alerta	alerta	Use the Alerta webhook plugin payload; closed or resolved status clears. Validate source severity/status mappings.
PagerDuty Events API v2 senders	pagerduty	Point the sender's Events API URL at your AckNexa API path /v2/enqueue and use the integration secret as the routing key. trigger opens or updates, resolve clears, and acknowledge is accepted and ignored.
Custom monitoring (Zabbix, Nagios, Checkmk, scripts)	generic	Send the canonical-style JSON fields shown below.

Email intake and SNMP traps are not available yet.

Create and secure an integration#

Open Integrations and choose the source kind, owning service, name, enabled state, and authentication mode.
Copy the webhook path and newly issued secret. The stored secret is hashed, so plaintext recovery is not available later.
Configure the sender's exact deployment API URL. Keep secrets out of URLs, logs, screenshots, and shared shell history.
Use token/HMAC mode or HMAC-only mode as required by policy.
Send a representative test, inspect processing status and routing, then verify acknowledgement.

Generic payload#

json

{
  "alert_name": "DatabaseUnavailable",
  "resource": "db-01",
  "environment": "production",
  "severity": "critical",
  "status": "firing",
  "summary": "Database health check failed",
  "started_at": "2026-09-21T09:00:00Z",
  "labels": { "team": "platform" }
}

Use your actual current source timestamp; the example is illustrative. Send recovery with the same stable identity and appropriate source lifecycle timestamps. Test the exact payload shape for your integration kind.

Authenticated request#

curl --request POST "https://api.example.internal/integrations/webhook/INTEGRATION_ID" \
  --header "Content-Type: application/json" \
  --header "X-AckNexa-Key: YOUR_WEBHOOK_SECRET" \
  --header "Idempotency-Key: YOUR_STABLE_EVENT_ID" \
  --data-binary @event.json

Signature v2 (recommended)#

Sign TIMESTAMP + '.' + IDEMPOTENCY_KEY + '.' + RAW_BODY with HMAC-SHA256 using the webhook secret itself as the key, where TIMESTAMP is the X-AckNexa-Timestamp header exactly as sent and IDEMPOTENCY_KEY is the Idempotency-Key header (empty if absent). Send X-AckNexa-Signature: v2=HEX_SIGNATURE. The server stores the secret encrypted with the deployment configuration key, so database or backup access alone cannot forge requests, and replaying a request under a new idempotency key fails. Choose 'Require signature v2' on the integration to refuse tokens and v1 signatures; rotate older secrets once first.

HMAC mode (v1, legacy)#

Sign RFC3339_TIMESTAMP + '.' + RAW_BODY with HMAC-SHA256 using SHA256(webhook_secret) as the binary HMAC key. Send X-AckNexa-Timestamp and X-AckNexa-Signature: sha256=HEX_SIGNATURE. The timestamp must be within five minutes. Sign the exact bytes transmitted; JSON reformatting after signing changes the signature. When a signature is supplied, it must validate even if a token is also supplied.

Rotation and retirement#

Rotate the integration secret through the supported action, update the sender, and verify a successful event. Do not assume a grace period for the previous secret. Archive an integration when retiring it; retain its history. Identity-affecting changes on an integration with history can require creating a new integration.

Heartbeat monitors#

A heartbeat turns silence into a page: a backup that never ran, a cron job that hung, a pipeline that stopped.

Open Heartbeats under Configure and create a heartbeat with its service, the job's interval, a grace period and the severity to raise.
Copy the ping URL, which is shown once, and call it at the end of the job. GET, POST and HEAD all count.
If no ping arrives within the interval plus grace, an incident opens on the service and its escalation policy pages the team. The next ping resolves it.

curl -fsS -m 10 "https://api.example.internal/heartbeat/YOUR_HEARTBEAT_TOKEN" >/dev/null

Heartbeat incidents use the normal alert pipeline, so routing rules, maintenance windows, deduplication and auto-resolution apply. Pausing a monitor stops the clock; rotating the token invalidates the old URL immediately.

Outbound webhooks#

Webhooks, under Configure, sends selected incident events (created, acknowledged, escalated, assigned, note, update, snoozed, resolved) to your own HTTPS endpoint, for the whole organization, one team or one service. The host must be in the deployment's NOTIFICATION_WEBHOOK_HOSTS allowlist, and private addresses also need NOTIFICATION_PRIVATE_CIDRS. Each request carries X-AckNexa-Signature, an HMAC-SHA256 over the timestamp and body with the secret shown once at creation; verify it and reject old timestamps. Deliveries retry with backoff, and a retry after a timeout can repeat a delivery your endpoint already processed.