Webhook Notifications

Notification lifecycle

The engine waits while diagnostic status is Pending. It then compares recommendations with the previous snapshot and can build messages for new, ongoing, and recovered recommendations. Cooldown and duplicate policies may filter recommendation notifications. Recovery messages are built separately and use Info severity.

Alert payload

{
  "severity": "Advisory",
  "title": "High CPU Utilization",
  "summary": "CPU utilization is elevated. Review active workloads and monitor sustained CPU usage.",
  "device": {"hostname": "example-host", "ip": "192.0.2.10", "mac": "02:00:00:00:00:01"},
  "evidence": ["High CPU Utilization", "Top CPU consuming processes detected.", "consumer_1: example-worker (74.9%)"]
}

Device and process details are sanitized examples.

Recovery payload

{
  "severity": "Info",
  "title": "CPU Utilization Recovered",
  "summary": "CPU utilization has returned to a healthy operating level.",
  "device": {"hostname": "example-host", "ip": "192.0.2.10", "mac": "02:00:00:00:00:01"}
}

Recovery messages normally omit evidence, because the recovery builder does not explicitly add it.

Payload fields

Evidence can contain diagnostic titles, descriptions, and key/value details. A message that no specific root cause was identified does not prove every possible cause was evaluated. The internal recommendation ID is not included.

Configuration

[notifications]
cooldown=15
cooldown_unit=minutes

[notifications.console]
enabled=true

[notifications.webhook]
enabled=true
scheme=http
host=127.0.0.1
port=8081
path=/webhook
token=

These are defaults from the configuration structure; verify exact key names and syntax against the configuration shipped with the package.

• scheme: http or https
• host, port, path: receiver location
• token: optional bearer token for HTTP; required by validation when HTTPS webhooks are enabled

The default host is loopback, suitable for a receiver on the same machine. Remote delivery requires network reachability and access controls.

Authentication and transport

When configured, NetIntel sends Authorization: Bearer YOUR_TOKEN. With an empty token, the Authorization header is omitted. HTTPS enables server-certificate and hostname verification; use a valid certificate and configure a token. HTTP does not encrypt the payload or token, so avoid sending bearer tokens over untrusted networks.

Delivery is successful for a 2xx response. Transport errors and non-2xx responses are treated as failures.

Cooldown and duplicate filtering

The default cooldown is 15 minutes. Its key is notification title plus summary, not explicitly device identity; do not assume it is a per-device rate limit. Duplicate filtering is disabled by default in the configuration structure.

Testing and troubleshooting

python3 /usr/share/doc/netintel/examples/webhook_receiver.py

The development receiver listened at http://127.0.0.1:8081/webhook. Verify the example path and listener settings in your installed package. Do not expose a test receiver to an untrusted network.

1. Confirm webhooks are enabled.
2. Check host, port, and path.
3. Confirm the receiver is reachable.
4. Inspect receiver logs and response status.
5. For HTTPS, validate certificate and hostname.
6. Check Bearer token configuration.
7. Consider cooldown or duplicate filtering.
8. Remember evidence is optional.

Operational context for AI workflows

External AI workflows can consume webhook events to explain incidents, correlate them with deployment or application events, or assist operators. These are integration possibilities, not AI features implemented by NetIntel. NetIntel remains the deterministic source of the operational context it exposes.

Read the REST API Reference →