Webhooks

Webhooks

Knightwatch can POST process and system events to one or more HTTP endpoints. Useful for integrating with external orchestration, alerting, or logging pipelines.

Usage

Enable webhooks with --with-webhook and provide one or more targets via --webhook:

knightwatch --pid <PID> --with-webhook --webhook https://example.com/hook --webhook https://other.com/hook

Webhook URLs can also be stored in persistent config and are merged with any --webhook flags at runtime (deduplicated). See Persistent Configuration.

Payload Format

{
  "version": "1.0.0",
  "event": "process.children_exited",
  "timestamp": "2025-01-01T00:00:00Z",
  "data": {
    "pids": [5678, 5679]
  }
}

Failed deliveries are retried up to 3 times with exponential backoff.

Process Events

Event	Description
process.initial_snapshot	First capture after startup
process.children_appeared	New child processes detected
process.children_exited	One or more children exited
process.all_children_gone	All children have exited
process.root_exited	Root process exited
process.work_complete	Work-done condition met

System Resources Events

Requires --system-resources.

Event	Description	Key data fields
resources.initial_snapshot	First hardware snapshot	snapshot
resources.tick	Periodic hardware snapshot	snapshot
resources.cpu_threshold_exceeded	CPU crossed warning threshold	usage_percent, threshold
resources.memory_threshold_exceeded	Memory crossed warning threshold	usage_percent, threshold
resources.disk_threshold_exceeded	Disk crossed warning threshold	mount_point, usage_percent, threshold
resources.battery_low	Battery charge below threshold	charge_percent, threshold
resources.battery_state_changed	Battery state changed	state

Systemd Events

Requires --systemd (Linux only).

Event	Description	Key data fields
systemd.initial_snapshot	First unit snapshot after startup	timestamp, unit_count, failed_count, active_count, inactive_count
systemd.tick	Periodic unit snapshot	timestamp, unit_count, failed_count, active_count, inactive_count
systemd.unit_failed	A unit transitioned to failed	unit_name, previous_state
systemd.unit_recovered	A previously failed unit recovered	unit_name
systemd.unit_appeared	A new unit became visible	unit_name, active_state, sub_state, description
systemd.unit_disappeared	A unit is no longer present	unit_name