Notifications

Insights can push an alert to an external endpoint whenever an audit check changes state. Each epoch it diffs the check results against the previous epoch and delivers the transitions — a check that started firing, or one that resolved — to every endpoint subscribed to that check code. Nothing is delivered while a check's state is unchanged.

Endpoint Types

Two endpoint types are supported. They share the same configuration fields and differ only in payload shape:

webhook receives the full payload envelope (status, alerts, group labels, and so on), compatible with an Alertmanager webhook_config receiver.
alertmanager receives a bare alert array, compatible with the Alertmanager v2 POST /api/v2/alerts API.

Configuration

Endpoints are defined in the YAML config file only — there is no equivalent flag or environment variable. Each endpoint accepts:

Field	Description	Default
`name`	Human-readable name; must be unique across all endpoints	—
`url`	URL to POST to; must be `http` or `https`	—
`enabled`	Whether the endpoint is active	`true`
`timeout`	HTTP request timeout (range `1s`–`300s`)	`10s`
`max-retries`	Delivery attempts before giving up (range `1`–`10`)	`3`
`auth-type`	`basic`, `bearer`, `hmac`, or empty for none	none
`auth-user`	Username for basic auth	—
`auth-token`	Password (basic), token (bearer), or signing secret (hmac)	—
`subscriptions`	Check codes this endpoint is subscribed to	—

Every endpoint is validated at startup. A missing or non-http(s) URL, a duplicate name, an unknown auth-type, or an out-of-range timeout or max-retries fails startup with an error naming the offending entry — an endpoint is never silently dropped, so you can't believe alerting is on while it never delivers.

# config.yaml
notifications:
  webhook:
    - name: 'PagerDuty Relay'
      url: 'https://example.com/webhook'
      enabled: true
      timeout: 10s
      max-retries: 3
      auth-type: 'bearer'
      auth-token: '…'
      subscriptions:
        - SERVER_001
        - JETSTREAM_001
  alertmanager:
    - name: 'local-am'
      url: 'http://localhost:9093/api/v2/alerts'
      subscriptions:
        - SERVER_001

Set --web.external-url to the public URL of the instance so the links inside alert payloads resolve back to it.

Web UI

The Notifications page in the web UI is read-only apart from a Test button on each endpoint's detail page, which delivers a synthetic firing alert to that endpoint and reports the result inline. Endpoints themselves are created and edited only in the config file.

Try it locally

You can see a delivery end to end without waiting for a real check to change state. Run a local receiver, start Insights with the config above, and click Test on the endpoint's detail page:

docker run --rm -p 9093:9093 prom/alertmanager   # a local receiver
./insights serve -c config.yaml                  # start Insights
# → Notifications UI → "local-am" → Test

A firing alert appears in Alertmanager at http://localhost:9093.

For the complete field reference and every config key, see Configuration.