Monitoring HESK with Vigilmon

HESK (Help Desk Software) is a free PHP helpdesk used by thousands of small and medium organizations for IT support and customer service. Its main virtue is radical simplicity: no complex dependencies, no framework overhead, no CLI tools. You upload the files, configure the database, and it works. But that simplicity cuts both ways — HESK has no built-in health endpoint, no metrics API, and no native monitoring hooks. If the server goes down or the email polling cron stops running, there's no alert mechanism unless you add one externally. Vigilmon provides exactly that external monitoring layer.

What You'll Set Up

• HTTP uptime monitor for the HESK login page with PHP response keyword check
• API endpoint monitor for HESK 3.x REST API installations
• SSL certificate expiry alerts for HTTPS HESK deployments
• Heartbeat monitor for HESK's email polling cron job (incoming ticket creation)

Prerequisites

• HESK 3.x installed and accessible over HTTP or HTTPS
• SSH access to the server to configure cron jobs
• A free Vigilmon account

Step 1: Monitor the HESK Web UI

HESK's home page (index.php) is the primary availability indicator. It renders when PHP is executing correctly and the MySQL database is accessible. No database = no page.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your HESK URL: https://support.yourdomain.com/index.php
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Enable Keyword match and enter: HESK
7. Click Save.

The keyword check is important for HESK specifically. Because HESK has no native health endpoint, the homepage is your best proxy for system health. The keyword HESK appears in the page title and meta tags of every HESK page and is absent when PHP returns a blank page or database error.

For a stronger check, use a string that appears only in the logged-out state:

Login to your help desk

This confirms the login form rendered — which requires PHP execution, database connectivity, and session handling to all be working.

Step 2: Monitor the HESK API (HESK 3.x)

HESK 3.0 introduced a REST API at /api/. The API endpoint is a more reliable health check than the homepage because it produces a structured JSON response that's easier to validate.

1. Click Add Monitor in Vigilmon.
2. Set Type to HTTP / HTTPS.
3. Enter the API base URL: https://support.yourdomain.com/api/
4. Set Expected HTTP status to 200 (unauthenticated requests return available endpoints).
5. Enable Keyword match and enter: api_version
6. Set Check interval to 5 minutes.
7. Click Save.

If you have API authentication configured, use a valid token to probe an authenticated endpoint:

1. Add a custom request header:
   • Header name: Authorization
   • Header value: Bearer YOUR_HESK_API_TOKEN
2. Change the URL to: https://support.yourdomain.com/api/tickets
3. Set Expected HTTP status to 200.

An authenticated ticket list endpoint confirms that PHP, the database, and the API auth layer are all working.

Step 3: Add a Lightweight PHP Health Check

Since HESK has no built-in health endpoint, create a minimal one alongside HESK's files:

<?php
// healthcheck.php — place in your HESK web root
// Simple availability check: confirm PHP is running
echo json_encode(['status' => 'ok', 'timestamp' => time()]);
http_response_code(200);

For a database-aware health check:

<?php
// healthcheck.php
define('IN_SCRIPT', true);
require_once 'hesk_settings.inc.php';
require_once 'inc/common.inc.php';

// Test database connection
$link = hesk_dbConnect();
if (!$link) {
    http_response_code(503);
    echo json_encode(['status' => 'error', 'detail' => 'db_connect_failed']);
    exit;
}

echo json_encode(['status' => 'ok']);
http_response_code(200);

Upload healthcheck.php to your HESK web root, then add a Vigilmon monitor for it:

1. Click Add Monitor in Vigilmon.
2. Set Type to HTTP / HTTPS.
3. Enter: https://support.yourdomain.com/healthcheck.php
4. Set Expected HTTP status to 200.
5. Enable Keyword match and enter: "status":"ok"
6. Click Save.

This gives you an unambiguous database connectivity check that doesn't depend on parsing HTML.

Step 4: SSL Certificate Alerts

HESK installations often run on shared hosting or basic VPS setups where SSL certificate renewal is managed manually or via a simple cron job. Expired certificates lock out all users with a browser security warning.

Enable SSL monitoring on your main HESK monitor:

1. Open the monitor from Step 1.
2. Under SSL Certificate, enable Monitor certificate expiry.
3. Set Alert threshold to 21 days before expiry.
4. Click Save.

Check your current certificate expiry from the command line:

echo | openssl s_client -servername support.yourdomain.com \
  -connect support.yourdomain.com:443 2>/dev/null \
  | openssl x509 -noout -dates

For Let's Encrypt renewals, verify the renewal cron is active:

sudo certbot renew --dry-run
# or for acme.sh users:
acme.sh --renew -d support.yourdomain.com --dry-run

Step 5: Heartbeat Monitoring for HESK Email Polling

HESK can create tickets from incoming emails by polling a mailbox at a configured interval. This is done via a cron job that calls hesk_cron.php. If this cron job stops running — due to PHP errors, permission issues, or a misconfigured crontab — incoming emails are silently ignored.

Set up a Vigilmon heartbeat:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Name it HESK Email Polling.
3. Set Expected ping interval to match your cron schedule. For a 5-minute cron, enter 5 minutes.
4. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Add the heartbeat to your crontab:

crontab -e

Add the following (adjust path to match your installation):

*/5 * * * * php /var/www/html/hesk_cron.php && curl -s https://vigilmon.online/heartbeat/abc123

The && operator ensures the heartbeat ping is only sent if hesk_cron.php exits cleanly. A PHP fatal error or permission failure suppresses the ping, and Vigilmon fires an alert after the interval.

To capture cron errors for debugging, redirect stderr:

*/5 * * * * php /var/www/html/hesk_cron.php >> /var/log/hesk_cron.log 2>&1 && curl -s https://vigilmon.online/heartbeat/abc123

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add your preferred notification method: email, Slack, or a webhook.
2. Set Consecutive failures before alert to 2 on the web UI monitor — brief server restarts can cause isolated probe failures.
3. Set Consecutive failures to 1 on the database health check — a database failure is always urgent.
4. For the email polling heartbeat, use immediate alerting on the first missed ping — missed email polling means support requests are not being processed.

Suppress alerts during scheduled maintenance:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 15}'

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://support.domain.com/index.php | PHP down, nginx/Apache failure | | Keyword check | Login to your help desk in page | Database down, silent PHP error | | Health endpoint | /healthcheck.php | MySQL unreachable, PHP config broken | | API (HESK 3.x) | /api/tickets | API routing failure, auth broken | | SSL certificate | Support domain | Certificate expiry before user impact | | Cron heartbeat | Heartbeat URL every 5 min | Email polling stopped, tickets not creating |

HESK's simplicity is its greatest strength and its biggest monitoring blind spot. There's no built-in health API, no metrics endpoint, and no native alerting for background job failures. Vigilmon bridges that gap — turning HESK's web UI, database connectivity, and email polling cron into a fully monitored system without touching the HESK codebase.