MaxBack Watchdog — Notifications

The Watchdog can send notifications through email (SMTP) or webhooks whenever something happens that needs your attention — a failed backup, a stopped service, an expiring license, or low disk space.

How notifications work

Notifications flow through a simple pipeline:

1. An event happens — a backup completes, a service stops, disk space runs low
2. The VssWriter or Watchdog sends the event to the notification service
3. The Watchdog checks which channels are subscribed to that event type
4. Each matching channel delivers the notification — as an email or a webhook POST

You can set up multiple channels, each listening for different event types. For example, you might send backup failures to your ops team by email, and all events to a monitoring dashboard by webhook.

Setting up email notifications

Email notifications are sent through SMTP. You need an SMTP server — your company mail server, Microsoft 365, Gmail, or any other SMTP-capable service.

Create credentials

Most SMTP servers require authentication. Run:

maxback.vssclient watchdog credentials add

The command walks you through the setup. It asks for a name for the credential, the authentication type (Basic or OAuth2), a username, and the password. The password is encrypted and stored locally — it never leaves the machine.

Add an email channel

maxback.vssclient watchdog channels add

The command asks you step by step:

1. Channel name — pick something descriptive, like AlertMail or OpsTeam
2. Channel type — choose Smtp
3. SMTP host — your mail server, e.g. mail.example.com
4. Port — defaults to 587
5. Use TLS — defaults to yes
6. Sender address — the "from" address on the emails
7. Recipients — one or more email addresses, comma-separated
8. Credential — pick one of your stored credentials, or none for unauthenticated SMTP
9. Events — select which events should trigger a notification on this channel

After the channel is created, send a test to make sure everything works:

maxback.vssclient watchdog channels test

The test sends a sample notification through the full pipeline. The Watchdog service must be running. You'll see OK or FAIL for each channel.

Setting up webhook notifications

Webhooks send a JSON payload to an HTTP endpoint of your choice — a monitoring system, a chat integration, a custom API, or anything that can receive POST requests.

maxback.vssclient watchdog channels add

Choose Webhook as the channel type. The command asks for a name, the endpoint URL, and which events to subscribe to. If your endpoint requires authentication, you can assign a credential (Basic or OAuth2) — the same way as with email channels.

See Webhook payload format below for the JSON structure your endpoint will receive.

Managing channels and credentials

To see what's configured:

maxback.vssclient watchdog channels list
maxback.vssclient watchdog credentials list

To change a channel — for example, to add recipients or change which events it listens for:

maxback.vssclient watchdog channels set

The command asks which channel to update, then walks you through the current settings so you can change what you need. You can also pass the channel name and only the fields you want to change on the command line — see the Command-Line Reference for all options.

To change the stored password or client secret for a credential:

maxback.vssclient watchdog credentials secret

To remove a channel or credential:

maxback.vssclient watchdog channels remove
maxback.vssclient watchdog credentials remove

Email format

Email notifications come in two formats depending on the event type.

Backup and restore results include a summary table (database, backup type, result, start and end time, duration) followed by a detailed log of all operations and their results.

Alert notifications (service down, missing backup, license issues, disk space) include a severity banner, a message describing what happened, and a details table with context like drive name, free space, expiration date, or service name.

Both formats support light and dark mode in email clients that support it.

Webhook payload format

Webhook notifications are sent as HTTP POST requests with a JSON body. The payload uses snake_case field names.

Payload structure

{
  "version": "1.0",
  "event_type": "BackupFailed",
  "host": "SERVER01",
  "event": {
    "event_type": "BackupFailed",
    "db_name": "PRD",
    "message": "Backup session failed",
    "severity": "Error",
    "session": { ... },
    "details": null
  }
}

Top-level fields

Event object

Session object (backup/restore events)

Present when event_type is one of: BackupCompleted, BackupWarning, BackupFailed, RestoreCompleted, RestoreWarning, RestoreFailed.

{
  "session": {
    "log_type": "BackupLog",
    "db_name": "PRD",
    "start_time": "2025-04-04T22:00:00Z",
    "end_time": "2025-04-04T23:15:00Z",
    "result": "Failed",
    "entries": [
      {
        "type": "Operation",
        "name": "Create Snapshot",
        "result": "Completed",
        "start_time": "2025-04-04T22:00:01Z",
        "end_time": "2025-04-04T22:00:03Z"
      },
      {
        "type": "Event",
        "severity": "Error",
        "message": "Failed to copy log backup: disk full"
      }
    ]
  }
}

Details object (alert events)

Present when event_type is one of: MissingBackup, ServiceDown, ServiceRestartFailed, LicenseExpiring, LicenseExpired, LicenseMissing, LogDiskSpaceLow, LogDiskSpaceCritical.

The details object contains context-specific key-value pairs. Examples:

Missing backup:

{
  "details": {
    "backup_type": "Full",
    "window_start": "2025-04-04T22:00:00",
    "window_end": "2025-04-05T10:00:00",
    "cron": "0 22 * * *"
  }
}

Disk space low:

{
  "details": {
    "drive": "E:",
    "free_mb": "342",
    "total_mb": "102400",
    "threshold_mb": "500"
  }
}

License expiring:

{
  "details": {
    "expiration_date": "2025-05-01",
    "days_remaining": "27"
  }
}

Event types reference

HTTP details

• Method: POST
• Content-Type: application/json
• Authentication: Authorization: Basic ... or Authorization: Bearer ... if a credential is assigned, no header otherwise
• Timeout: 30 seconds
• Success: Any 2xx response
• Failure: Logged on the Watchdog, no retry (the event is not re-sent)