Documentation
Advanced Topics
JSON Output - Machine-Readable Update Reports

JSON Output - Machine-Readable Update Reports

Update-Watcher can output check results and configuration status as structured JSON. This enables integration with monitoring tools, custom notification pipelines, dashboards, and scripting workflows.

Enabling JSON Output

Run Results

Add --format json to the run command:

Terminal
update-watcher run --format json

The JSON output contains the full check results: each checker’s status, the list of available updates, error messages for failed checkers, and summary totals.

Configuration Status

The status command also supports JSON:

Terminal
update-watcher status --format json

This outputs the resolved configuration as JSON, including all watchers, notifiers, settings, and cron status.

JSON Structure

The run command produces output with the following structure:

output.json
{
  "hostname": "web-prod-01",
  "timestamp": "2025-04-15T07:00:12Z",
  "total_updates": 5,
  "total_security_updates": 2,
  "checkers": [
    {
      "type": "apt",
      "status": "success",
      "updates": 3,
      "security_updates": 2,
      "packages": [
        {
          "name": "openssl",
          "current_version": "3.0.2-0ubuntu1.14",
          "available_version": "3.0.2-0ubuntu1.15",
          "security": true
        },
        {
          "name": "libssl3",
          "current_version": "3.0.2-0ubuntu1.14",
          "available_version": "3.0.2-0ubuntu1.15",
          "security": true
        },
        {
          "name": "curl",
          "current_version": "7.81.0-1ubuntu1.15",
          "available_version": "7.81.0-1ubuntu1.16",
          "security": false
        }
      ]
    },
    {
      "type": "docker",
      "status": "success",
      "updates": 2,
      "security_updates": 0,
      "containers": [
        {
          "name": "nginx-proxy",
          "image": "nginx:1.25",
          "update_available": true
        },
        {
          "name": "redis-cache",
          "image": "redis:7.2",
          "update_available": true
        }
      ]
    }
  ]
}

Parsing with jq

💡
jq is the standard tool for processing JSON on the command line. Pipe the JSON output directly to jq for filtering, counting, and transforming results.
Example: Count Total Updates
Terminal
update-watcher run --format json | jq '.total_updates'
Example: List Only Security Updates
Terminal
update-watcher run --format json | jq '[.checkers[].packages[]? | select(.security == true)]'
Example: Get Checker Types with Updates
Terminal
update-watcher run --format json | jq '[.checkers[] | select(.updates > 0) | .type]'
Example: Extract Package Names
Terminal
update-watcher run --format json | jq '[.checkers[].packages[]?.name] | unique'
Example: Filter by Checker Type

Get only APT results:

Terminal
update-watcher run --format json | jq '.checkers[] | select(.type == "apt")'
Example: Check for Failed Checkers
Terminal
update-watcher run --format json | jq '[.checkers[] | select(.status != "success") | .type]'
Example: Pretty-Print the Full Report
Terminal
update-watcher run --format json | jq .

Integration Examples

Write Results to a File

Save the JSON report for later processing:

Terminal
update-watcher run --format json > /var/log/update-watcher-report.json

Send to a Custom Webhook

💡
Use --notify=false when sending to a custom webhook to avoid duplicate notifications through the built-in notifiers.

Post the JSON report to a custom HTTP endpoint:

Terminal
update-watcher run --format json --notify=false | \
  curl -s -X POST -H "Content-Type: application/json" \
    -d @- https://monitoring.example.com/api/updates

Conditional Alerting Script

Build a custom alerting workflow based on security updates:

Terminal
#!/bin/bash
REPORT=$(update-watcher run --format json --notify=false)
SECURITY_COUNT=$(echo "$REPORT" | jq '.total_security_updates')

if [ "$SECURITY_COUNT" -gt 0 ]; then
  echo "CRITICAL: $SECURITY_COUNT security updates available" | \
    mail -s "Security Updates on $(hostname)" admin@example.com
fi

Feed into Monitoring Systems

Combine JSON output with exit codes for monitoring integration:

Terminal
#!/bin/bash
RESULT=$(update-watcher run --format json --notify=false)
EXIT_CODE=$?

case $EXIT_CODE in
  0) echo "OK - No updates available" ;;
  1) echo "WARNING - $(echo $RESULT | jq -r '.total_updates') updates available" ;;
  2) echo "WARNING - Partial checker failure" ;;
  3) echo "CRITICAL - All checkers failed" ;;
  4) echo "CRITICAL - Configuration error" ;;
esac

exit $EXIT_CODE

Aggregate Across Servers

Collect reports from multiple servers into a central location:

Terminal
for server in web-01 web-02 db-01; do
  ssh "$server" "update-watcher run --format json --notify=false" > "reports/${server}.json"
done

# Summarize total updates across all servers
cat reports/*.json | jq -s '[.[].total_updates] | add'

Combining with Other Flags

JSON output can be combined with other run flags:

Terminal
# JSON output for a single checker
update-watcher run --format json --only apt

# JSON output without sending notifications
update-watcher run --format json --notify=false

# Verbose JSON (debug info goes to stderr, JSON to stdout)
update-watcher run --format json --verbose
When --verbose is used with --format json, the debug output is written to stderr so it does not interfere with the JSON on stdout. This means you can redirect them separately.
Terminal
update-watcher run --format json --verbose 2>/var/log/debug.log > report.json

Related

  • Exit Codes – Use exit codes alongside JSON for scripting.
  • run – Full run command reference.
  • status – JSON output for configuration status.
  • Webhook Notifier – Send JSON payloads to custom endpoints natively.
Exit Codes - Scripting Reference