How to Monitor Invoice Ninja with Vigilmon

Invoice Ninja is the leading open-source invoicing and billing platform: self-hosted, multi-currency, and designed to replace SaaS invoicing tools without the recurring subscription cost. When Invoice Ninja goes down, clients can't view invoices, payments fail to process, and billing records diverge from reality. Vigilmon monitors your Invoice Ninja instance continuously from multiple geographic regions and alerts you the moment something breaks.

What You'll Set Up

• Vigilmon HTTP monitor for the Invoice Ninja web UI
• A monitor for the /api/v1/ping health endpoint
• A queue worker heartbeat monitor
• An SSL certificate expiry alert

Prerequisites

• A running Invoice Ninja v5 instance (self-hosted, Laravel-based)
• A free Vigilmon account
• SSH access to your server (for queue heartbeat setup)

Why Invoice Ninja Needs External Monitoring

Invoice Ninja is a Laravel application with multiple moving parts: a web server (Nginx or Apache), PHP-FPM, a MySQL/MariaDB database, and a queue worker process (php artisan queue:work) that handles background email dispatch, PDF generation, and recurring invoice creation. If the queue worker dies — which happens silently on many servers — invoices stop being sent and recurring billing fails, while the web UI continues working normally.

External monitoring from Vigilmon detects failures at every layer: a failing web UI, an unhealthy API ping, a stopped queue worker, or an expired SSL certificate.

Step 1: Monitor the Invoice Ninja Web UI

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Invoice Ninja URL, e.g. https://invoices.yourdomain.com.
4. Set Check interval to 1 minute.
5. Set Expected status code to 200.
6. Click Save.

This checks that Nginx, PHP-FPM, and the Laravel bootstrap are working. A crash in any of these layers triggers an alert within one minute.

Step 2: Monitor the /api/v1/ping Health Endpoint

Invoice Ninja exposes a lightweight health check endpoint at /api/v1/ping that verifies the application is alive and the database is reachable.

1. Click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter https://invoices.yourdomain.com/api/v1/ping.
4. Set Expected status code to 200.
5. In Expected body contains, enter "message".
6. Click Save.

A healthy response looks like:

{
  "message": "pong",
  "version": "5.10.x"
}

This catches database failures that the web UI check misses. Invoice Ninja's login page may appear to load from session cache even when the database is down, but /api/v1/ping fails immediately.

Step 3: Set Up a Queue Worker Heartbeat Monitor

The Invoice Ninja queue worker handles critical background tasks: sending invoices via email, generating PDF previews, and processing recurring invoice schedules. If the worker process dies, these tasks queue silently and never execute.

Create the Heartbeat Monitor

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Name it Invoice Ninja Queue Worker.
3. Set the expected ping interval to 5 minutes.
4. Copy the generated heartbeat URL — e.g. https://vigilmon.online/heartbeat/YOUR_TOKEN.

Add a Heartbeat Ping to the Queue Worker Supervisor

If you manage the queue worker with Supervisor, add a wrapper script. Edit your Supervisor config (typically at /etc/supervisor/conf.d/invoiceninja-worker.conf) to use a wrapper:

[program:invoiceninja-worker]
command=/usr/bin/php /var/www/invoiceninja/artisan queue:work --sleep=3 --tries=3 --max-time=3600
directory=/var/www/invoiceninja
autostart=true
autorestart=true
user=www-data

Then add a cron job that pings Vigilmon as long as the worker process is alive:

*/5 * * * * pgrep -f "queue:work" > /dev/null && curl -s https://vigilmon.online/heartbeat/YOUR_TOKEN

This approach pings Vigilmon only while the queue worker is running. If Supervisor fails to restart the worker after a crash, the ping stops and Vigilmon fires a missing-heartbeat alert within 5 minutes.

Step 4: Monitor the SSL Certificate

Invoice Ninja handles financial data — an expired SSL certificate not only disrupts access but erodes client trust immediately.

1. In Vigilmon, click Add Monitor → SSL Certificate.
2. Enter your Invoice Ninja domain, e.g. invoices.yourdomain.com.
3. Set Alert days before expiry to 30.
4. Click Save.

Vigilmon checks the certificate daily. You'll receive an alert 30 days before expiry, giving ample time to renew via Certbot (certbot renew) before clients see a security warning.

Step 5: Configure Alert Channels

Slack Webhook

1. Create a Slack incoming webhook for your #billing-alerts channel.
2. In Vigilmon, go to Alert Channels → Add Channel → Webhook.
3. Paste the webhook URL and use this payload:

{
  "text": "🚨 *{{monitor_name}}* is {{status}}!\nURL: {{url}}\nTime: {{timestamp}}"
}

4. Attach the channel to all four Invoice Ninja monitors.

Email Alert

Vigilmon sends email alerts to your account email by default. For a billing-critical system, consider adding a second email address (e.g. your finance team lead) via Alert Channels → Add Channel → Email.

Step 6: Verify the Setup

1. Test the ping endpoint: Run curl https://invoices.yourdomain.com/api/v1/ping and confirm the JSON response matches what Vigilmon expects.
2. Simulate a queue failure: Stop the queue worker (sudo supervisorctl stop invoiceninja-worker) and confirm Vigilmon fires a missing-heartbeat alert within the expected interval.
3. Check the dashboard: The Vigilmon response time history shows whether PDF generation or email dispatch is causing latency spikes on the web tier.

Going Further

• Response time alert: Invoice Ninja PDF generation can add latency on busy servers. Set a warn threshold at 2000ms and critical at 5000ms to catch performance regressions before they become outages.
• Recurring invoice check: Add a secondary cron job that runs php artisan ninja:send-recurring and pings a separate Vigilmon heartbeat — this confirms recurring invoices are being dispatched even if the queue worker is alive but misconfigured.
• Staging environment: Mirror all monitors on your staging Invoice Ninja instance so upgrades are verified before touching production billing data.

Your Invoice Ninja server is now monitored end-to-end: web UI availability, API health, queue worker continuity, and SSL certificate safety — with alerts routing to the right people before clients notice a problem.