Event Hooks

Event hooks let you react to events by running shell commands on the same machine as superd, or by POSTing the event JSON to an HTTP(S) webhook — no plugin or license required. Each [[event_hooks]] entry is either a command or a url; OSS does not have a separate “webhook notifications” config — webhook POST is an event hook.

Configuration

Define global hooks in super.toml. Each hook is either a local command (command) or a webhook (url) — if url is set, command is ignored.

# super.toml — [event_hooks]
[[event_hooks]]
id = "archive-on-fatal"
command = "/opt/super/archive.sh"
events = ["process_fatal"]
programs = ["*"]          # default: all programs
async = true              # default: true
timeout_secs = 30         # default: 30

[[event_hooks]]
command = "python3 /etc/super/handler.py"
events = ["process_backoff", "process_fatal"]
programs = ["api-server", "worker"]
async = false             # run sequentially (still non-blocking for the manager)

# super.toml — [event_hooks]
[[event_hooks]]
id = "ops-alert"
url = "https://ops.example.com/hooks/super"
headers = { Authorization = "Bearer s3cret-token" }
events = ["process_fatal", "process_backoff"]
programs = ["*"]
async = true              # default: true (fire-and-forget)
timeout_secs = 10         # request timeout in seconds

Webhook requests are POST with Content-Type: application/json and the same JSON body used for local hooks. Non-2xx responses and timeouts are logged as warnings only — webhooks never block process management.

Reload hooks without restarting programs:

super reload    # re-reads super.toml, including [[event_hooks]]

JSON payload (stdin / webhook body)

Each matching hook receives one JSON object — on stdin for command hooks, as the request body for webhooks:

{
  "event": "process_fatal",
  "timestamp": "2026-07-06T16:16:00Z",
  "hostname": "prod-1",
  "version": "1.1.9",
  "program": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "web-server",
    "pid": 1234,
    "uptime_secs": 502
  },
  "payload": {
    "exit_code": 137,
    "signal": 9,
    "msg": "Stopped after 3 retries.",
    "log_tail": null
  }
}

system_startup / system_shutdown events omit the program field.

Environment variables

In addition to stdin JSON, hooks receive:

Behavior

• Commands run via sh -c (pipes and redirects work).
• Hooks never block process management — failures are logged only.
• async = true (default): each hook runs in its own task.
• async = false: hooks for the same event run one after another in a background task.
• Non-zero exit or timeout → warning log; no impact on managed processes.

OSS vs licensed notifications

Related

• Events overview — the three-layer event system
• Event Types — full event catalog
• Event History — persisted record of all events
• Lifecycle Hooks — per-program start/stop scripts
• Config Reference — [[event_hooks]]