Service Event Notifications

Table of Contents

1. Introduction
2. Requirements
   1. Common
   2. For Toast notifications (ServyFailureNotification.ps1)
   3. For Email notifications (ServyFailureEmail.ps1)
   4. For Heartbeat Ping URL Notifications
3. Setup Toast Notifications via Task Scheduler
4. Manual Notification (Optional)
5. Email Notifications
   1. Generating credentials as SYSTEM
6. Heartbeat Ping URL Notifications
7. External Alerts via Heartbeat URLs (Slack, Teams, Phone Call, etc.)
   1. How can I get failure alerts sent to Slack, Microsoft Teams, Phone Call, or WhatsApp?
8. Limitations
9. Tips
10. Troubleshooting

Introduction

Servy can notify users when a managed service fails by showing interactive Windows toast notifications, sending an email, or firing out-of-band HTTP heartbeat pings to external monitoring services. This allows administrators to be immediately aware of service crashes or health check failures without constantly monitoring the application interface.

Requirements

Common

• Servy must be installed and running.
• Access to the Windows Application Event Log.

For Toast notifications (ServyFailureNotification.ps1)

• Windows 10 or 11, Windows Server 2016+
• PowerShell 5.1+ (Windows Runtime toast APIs)

For Email notifications (ServyFailureEmail.ps1)

• Windows 7 SP1+ / Windows Server 2008 R2+
• PowerShell 5.1+ (Get-WinEvent)
• SMTP relay reachable from the host

For Heartbeat Ping URL Notifications

• Direct or proxy-routed HTTP/HTTPS outbound connectivity to your designated monitoring endpoint (e.g., healthchecks.io, Uptime Kuma, Pingdom).

Setup Toast Notifications via Task Scheduler

1. Install Servy as usual.
2. Ensure the notification script exists at:

   %ProgramFiles%\Servy\taskschd\ServyFailureNotification.ps1
   

3. Import the Scheduled Task:
   • Open Task Scheduler.
   • Click Import Task… from the right-hand Actions pane.
   • Navigate to and select:

     %ProgramFiles%\Servy\taskschd\ServyFailureNotification.xml
     

   • In the General Tab:
     • Ensure "Run only when user is logged on" is selected (Toasts cannot render if the user is not logged into an active desktop session).
     • Check "Run with highest privileges" to ensure the script has permission to read the Event Log.

Once configured, Windows will automatically trigger this task whenever Servy writes a new Error event to the Application log.

Important

If you are using the portable version of Servy, you must edit ServyFailureNotification.xml and replace {SERVY_INSTALL_PATH} with the absolute path to the directory containing your Servy executable.

Warning

The imported task runs with the highest privileges available to the account that imported it, and it runs the scripts in the taskschd folder of your Servy directory ({SERVY_INSTALL_PATH}\taskschd). Make sure that folder, and the Servy directory above it, can be written only by administrators. If a standard user can write there (a custom install directory such as C:\Servy, or a portable copy in a user-writable folder), that user can replace a script and have it run with administrator rights. The default %ProgramFiles%\Servy location is already admin-only.

Manual Notification (Optional)

You can test or run the notification script manually in a PowerShell window:

& "C:\Program Files\Servy\taskschd\ServyFailureNotification.ps1"

The script will automatically parse the Event Log for the latest Servy errors and display a toast containing the service name and the specific error message.

Note

The scheduled tasks are unaffected by the machine's PowerShell execution policy - they run through ServyFailureNotification.vbs, which invokes PowerShell with -ExecutionPolicy Bypass. Only this manual invocation is subject to it. If it is blocked, run the script the same way the task does rather than changing the machine policy:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\Program Files\Servy\taskschd\ServyFailureNotification.ps1"

Email Notifications

For server environments where users may not have an active desktop session, Servy can be configured to send email notifications.

1. Install Servy as usual.

2. Configure your SMTP settings by editing %ProgramFiles%\Servy\taskschd\smtp-config.xml:

   <?xml version="1.0" encoding="UTF-8"?>
   <SmtpConfig>
     <Server>smtp.example.com</Server>
     <Port>587</Port>
     <UseSsl>true</UseSsl>
     <TimeoutMs>30000</TimeoutMs>
     <From>servy.notifications@example.com</From>
     <To>admin1@example.com;admin2@example.com</To>
   </SmtpConfig>

3. To avoid hardcoding passwords in plaintext, the email script requires an encrypted XML credential file. Open PowerShell as Administrator and run the following block:

   $targetDir = "C:\Program Files\Servy\taskschd"
   $cred = Get-Credential
   $cred | Export-Clixml -Path (Join-Path $targetDir "smtp-cred.xml")

Important

CRITICAL SECURITY NOTE: Windows encrypts this XML file using the Data Protection API (DPAPI). This means the file can only be decrypted by the exact user account that created it. You must run the Get-Credential command while logged in as the same user account that will run the Scheduled Task. If the task runs as SYSTEM, you must generate the credentials as SYSTEM.

Generating credentials as SYSTEM

If you have explicitly changed the Scheduled Task to run as NT AUTHORITY\SYSTEM (via "Change User or Group..." - the imported task defaults to the account that imported it), you must generate smtp-cred.xml from a SYSTEM-context PowerShell session. The recommended approach is via PsExec:

# From an elevated admin prompt, after downloading PsExec:
psexec.exe -i -s powershell.exe

# In the new SYSTEM-context window (verify with: whoami → "nt authority\system"):
$targetDir = "C:\Program Files\Servy\taskschd"
$cred = Get-Credential
$cred | Export-Clixml -Path (Join-Path $targetDir "smtp-cred.xml")

If you cannot use PsExec, change the Scheduled Task to run under a dedicated service account instead - that account can then generate smtp-cred.xml from its own logon session.

4. Import the Scheduled Task:

   • Open Task Scheduler.
   • Click Import Task…
   • Select:

     %ProgramFiles%\Servy\taskschd\ServyFailureEmail.xml
     

   • In the General Tab:
     • Select "Run whether user is logged on or not".
     • Check "Run with highest privileges".
     • Ensure the user specified in the security options matches the user who generated smtp-cred.xml in Step 3.

Important

If you are using the portable version of Servy, you must edit ServyFailureEmail.xml and replace {SERVY_INSTALL_PATH} with the absolute path to the directory containing your Servy executable.

Warning

The imported task runs with the highest privileges available to the account that imported it, and it runs the scripts in the taskschd folder of your Servy directory ({SERVY_INSTALL_PATH}\taskschd). Make sure that folder, and the Servy directory above it, can be written only by administrators. If a standard user can write there (a custom install directory such as C:\Servy, or a portable copy in a user-writable folder), that user can replace a script and have it run with administrator rights. The default %ProgramFiles%\Servy location is already admin-only.

Heartbeat Ping URL Notifications

In addition to local toasts and emails, Servy supports real-time out-of-band notification pings directly to external uptime and health monitoring services (such as healthchecks.io, Uptime Kuma, or Pingdom).

Servy executes asynchronous HTTP GET calls based on operational lifecycle states:

• Startup Notification (/start): When --enableHeartbeatUrlFlags is enabled, Servy issues a ping to https://hc-ping.com/your-uuid/start upon service startup to notify your monitoring platform that the process has initialized.
• Periodic Health Check Ping: A health check that finds the process healthy in steady state pings the exact base URL (https://hc-ping.com/your-uuid) to refresh the uptime timer. A healthy check that follows one or more failed checks instead re-sends /start (when --enableHeartbeatUrlFlags is enabled), signalling that the service recovered - see Health Monitoring & Recovery for the full ping rules.
• Failure Alert Ping (/fail): When a child process crashes, health check retries fail, or restart quotas are exceeded, Servy immediately fires a ping to https://hc-ping.com/your-uuid/fail (when --enableHeartbeatUrlFlags is enabled) to trigger instant alerts across your connected platforms (Slack, PagerDuty, Teams, SMS).

.\servy-cli install `
  --name="MyWorkerService" `
  --path="C:\Services\Worker.exe" `
  --enableHealth `
  --heartbeatInterval="60" `
  --maxFailedChecks="3" `
  --recoveryAction="RestartService" `
  --heartbeatUrl="https://hc-ping.com/your-uuid" `
  --heartbeatUrlTimeoutSeconds="10" `
  --enableHeartbeatUrlFlags

For full details on configuring out-of-band ping intervals and timeout limits, see Integration with Monitoring Tools.

External Alerts via Heartbeat URLs (Slack, Teams, Phone Call, etc.)

How can I get failure alerts sent to Slack, Microsoft Teams, Phone Call, or WhatsApp?

Servy relies on out-of-band monitoring services to deliver real-time incident alerts. Point Servy's Heartbeat URL to a ping provider like healthchecks.io, which natively connects to downstream notification platforms.

1. Create a check in your monitoring service (e.g., healthchecks.io) and copy its unique ping URL.
2. Enter the URL into Servy's Heartbeat URL setting and enable Heartbeat URL Flags.
3. In your monitoring service dashboard, attach your preferred integration channels.

When Servy sends a /fail signal or stops pinging because the host machine went down, the monitoring platform triggers alerts to your configured channels, including:

• Chat & Collaboration: Slack, Microsoft Teams, Discord, Telegram, WhatsApp, Signal, Google Chat, Matrix, Mattermost, Rocket.Chat, Zulip.
• Incident Management & Webhooks: PagerDuty, Opsgenie, Splunk On-Call, Spike.sh, PagerTree, custom Webhooks.
• Direct Notifications: Email, SMS, Phone Call, Pushbullet, Pushover, ntfy, Gotify.
• Issue & Event Tracking: GitHub Issues, Trello, Prometheus.

Tip

For local or isolated alerting without an external ping service, you can also use Servy's Failure Program Path to execute a local script (such as a PowerShell script calling a Slack Webhook) after all recovery attempts fail.

Limitations

• Interactive Session Required: Toast notifications operate strictly in the user context (Session 1+). They will not appear if the task is run as SYSTEM (Session 0) or if the user is completely logged out.
• Event Log Dependency: Task Scheduler triggers for toast and email scripts are bound to the Windows Event Log. Notifications will only fire for events logged specifically by the "Servy" source with an Error level and an event ID in the Servy error ranges (3000-3199, see Event IDs); any other Error event of that source is ignored.
• Per-Run Cap: Each run of the toast or email script delivers at most 10 notifications. When more errors arrived since the last run, the newest 10 are delivered and the older ones are skipped and recorded in ServyWatermarkErrors.log in the taskschd folder. The event-ID filter and the cap live in the scripts, so a task imported from an earlier ServyFailureEmail.xml or ServyFailureNotification.xml gets them without a re-import.
• Credential Portability: The smtp-cred.xml file cannot be copied to another machine or used by another user account without being regenerated.
• Network Connectivity for Heartbeat Pings: Heartbeat URL pings require outbound HTTP/HTTPS communication. High-security offline environments without internet or proxy routing will drop out-of-band ping attempts.

Tips

• State Tracking: The PowerShell scripts maintain a .dat timestamp file (e.g., last-processed-toast.dat) in the taskschd directory to ensure they do not send duplicate alerts for the same error. If you need to test the notification pipeline, delete this file. Note: Only the single most recent error will be processed on the next run; older unread errors will be dropped to prevent alert floods. To replay history, set the file's contents to a timestamp older than the events you want to see (in ISO 8601 o format, e.g. 2026-01-01T00:00:00.0000000Z).
• Customization: You can safely edit the .ps1 scripts to customize the toast notification titles, icons, or email HTML bodies to fit your organization's monitoring standards.
• Defense in Depth: Combine Toasts, Emails, and Heartbeat Ping URLs. Toasts notify developers locally, emails notify sysadmins via inbox, and Heartbeat Ping URLs integrate into automated incident response tools (PagerDuty, Slack).

Troubleshooting

• Symptom: Emails are never sent, and the fallback log (ServyFailureEmail.log) shows "Key not valid for use in specified state" or a similar CryptographicException.
• Cause: This indicates the smtp-cred.xml credential file was encrypted by a different Windows account than the Scheduled Task's Run-As identity.
• Fix: Refer to the Generating credentials as SYSTEM section to regenerate the credential file using the exact user context configured in the task.