Events

Events

This page documents every event Knightwatch can emit. It's the shared reference for both Webhooks (HTTP POST delivery) and the API's SSE streams (/sse/*) — the two delivery mechanisms carry the exact same event set and payload shapes.

Payload Format

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

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
process.process_killed	A process was killed via a kill or kill-tree command

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

Docker Events

Requires --docker.

Event	Description	Key data fields
docker.initial_snapshot	First capture after startup	container_count, containers
docker.containers_appeared	New containers detected	container_count, containers
docker.containers_disappeared	Containers no longer visible	container_count, containers
docker.container_status_changed	A container's status changed	id, name, image, status, previous_status
docker.container_health_changed	A container's health status changed	id, name, image, health, previous_health
docker.container_oom_killed	A container was killed by the OOM killer	id, name
docker.container_action_result	Result of a stop/kill/start/restart/pause/unpause command	id, name, action, success

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