Background Monitoring: Webhooks & Observability

Hermes can run tasks in the background and notify external systems via webhooks. Essential for automation, monitoring dashboards, and integrating with your existing tools.

Background Tasks

Start a task in the background:

hermes run "analyze this codebase" --background

The task runs while you continue working. Check status anytime:

hermes tasks list
hermes tasks status <task-id>
hermes tasks output <task-id>

Background Task Config

# config.yaml
background:
  enabled: true
  max_concurrent: 5
  timeout: 3600  # 1 hour max
  persist_on_restart: true  # Resume after CLI restart

Webhooks

Send HTTP notifications when events occur:

webhooks:
  enabled: true
  endpoints:
    task_started:
      url: http://localhost:3000/hooks/task-start
      method: POST
    task_completed:
      url: http://localhost:3000/hooks/task-done
      method: POST
    task_failed:
      url: http://localhost:3000/hooks/task-error
      method: POST
    tool_called:
      url: http://localhost:3000/hooks/tool
      method: POST

Webhook Payload

task_started:

{
  "event": "task_started",
  "task_id": "abc123",
  "prompt": "analyze this codebase",
  "timestamp": "2026-04-22T10:30:00Z",
  "platform": "cli"
}

task_completed:

{
  "event": "task_completed",
  "task_id": "abc123",
  "duration_seconds": 45,
  "tokens_used": 3500,
  "tools_called": 12,
  "result": "success",
  "timestamp": "2026-04-22T10:30:45Z"
}

tool_called:

{
  "event": "tool_called",
  "task_id": "abc123",
  "tool": "file_read",
  "parameters": {"path": "/home/user/main.py"},
  "timestamp": "2026-04-22T10:30:15Z"
}

Webhook Authentication

webhooks:
  auth:
    type: bearer  # or 'basic', 'header'
    token: ${WEBHOOK_SECRET}

For HMAC signature verification:

webhooks:
  auth:
    type: hmac
    secret: ${WEBHOOK_HMAC_SECRET}
    header: X-Hermes-Signature

Retry Policy

webhooks:
  retry:
    enabled: true
    max_attempts: 3
    backoff: exponential  # or 'linear', 'fixed'
    initial_delay: 1000   # ms

Integration Examples

Slack Notifications

webhooks:
  endpoints:
    task_completed:
      url: https://hooks.slack.com/services/T00/B00/XXX
      method: POST
      transform:
        text: "Task completed: {{prompt}} ({{duration_seconds}}s)"

Discord Bot

webhooks:
  endpoints:
    task_failed:
      url: https://discord.com/api/webhooks/XXX/YYY
      method: POST
      transform:
        content: "⚠️ Task failed: {{prompt}}"

Grafana/Prometheus

Expose metrics endpoint:

monitoring:
  prometheus:
    enabled: true
    port: 9090
    path: /metrics

Metrics available:

• hermes_tasks_total{status="completed|failed"}
• hermes_tokens_used_total
• hermes_tool_calls_total{tool="..."}
• hermes_task_duration_seconds

Process Monitoring

Health Check Endpoint

monitoring:
  health:
    enabled: true
    port: 8080
    path: /health

Returns:

{
  "status": "healthy",
  "uptime": 3600,
  "active_tasks": 2,
  "memory_mb": 256
}

Systemd Integration

# /etc/systemd/system/hermes.service
[Unit]
Description=Hermes Agent
After=network.target

[Service]
ExecStart=/usr/local/bin/hermes serve
Restart=always
RestartSec=10
User=hermes

[Install]
WantedBy=multi-user.target

Log Streaming

Stream logs to external systems:

logging:
  stream:
    enabled: true
    format: json
    destinations:
      - type: file
        path: ~/.hermes/hermes.log
      - type: syslog
        address: localhost:514
      - type: http
        url: https://logs.example.com/ingest

Related Guides

• Webhooks Platform
• Security Hardening