Lago Monitoring with Vigilmon: Billing API, Event Ingestion & Invoice Queue Health Checks

Your billing infrastructure stopped processing subscription events two hours ago. New customers who signed up this morning haven't received invoices. A database migration ran last night, silently dropped a connection pool setting, and every Rails worker is now timing out on the events table. Nobody got an alert.

Lago is an open-source billing and metering infrastructure platform built on Ruby on Rails with a React frontend. It listens on port 3000 and manages the full billing lifecycle: event ingestion from your product, usage metering and aggregation, invoice generation, webhook delivery to your downstream systems, and subscription plan processing. Self-hosting Lago means you own the pipeline from the first billable event through charge calculation, invoice creation, and payment webhook delivery — and you own the responsibility of knowing when any link in that chain breaks.

Vigilmon probes your Lago installation from outside, the way a real API client would. If the event ingestion endpoint stops accepting data, if the invoice generation queue backs up, or if webhooks stop delivering, Vigilmon alerts you before billing failures become revenue recognition problems.

What You'll Build

• An HTTP monitor on the Lago API server
• An event ingestion pipeline health check
• A webhook delivery service monitor
• An invoice generation queue probe
• A database connectivity check via the organization API
• A subscription plan processing health monitor
• Alert channels for your billing operations team

Prerequisites

• A self-hosted Lago installation (v0.x or v1.x recommended)
• API server default port: 3000
• A free account at vigilmon.online

Step 1: Monitor the Lago API Server

The Lago Rails API on port 3000 is the foundation of your billing infrastructure. If it goes down, no events are ingested, no invoices are generated, and no subscription changes are processed.

Test the API server health endpoint:

curl -o /dev/null -s -w "%{http_code}" http://your-lago-host:3000/health

Lago exposes a /health endpoint that returns 200 OK with {"status":"ok"} when all core Rails services are running. A non-200 response or connection refused indicates the Puma web server has crashed or cannot serve requests.

Set up the Vigilmon monitor:

1. Log in to Vigilmon and click New Monitor → HTTP.
2. Set URL to http://your-lago-host:3000/health.
3. Set Check interval to 60 seconds.
4. Set Expected status code to 200.
5. Under Advanced → Keyword check, add:
   • Keyword present: ok
6. Save the monitor.

This check catches Puma process crashes, Rails boot failures, and dependency initialization errors that prevent the server from starting cleanly.

Step 2: Monitor the Event Ingestion Pipeline

Lago's event ingestion endpoint at /api/v1/events accepts billable usage events from your product. Every API call, storage byte, or computation unit your product meters flows through this endpoint. If it fails silently, you are under-billing customers for usage they are already consuming.

Test the event endpoint is reachable:

curl -o /dev/null -s -w "%{http_code}" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":{"transaction_id":"vigilmon-probe","external_customer_id":"probe","code":"probe_metric"}}' \
  http://your-lago-host:3000/api/v1/events

A healthy Lago event ingestion endpoint returns 200 with {"status":"ok"} when the event is accepted into the processing queue — even if the customer or metric code does not exist. A 422 Unprocessable Entity for a valid event schema indicates queue or database issues. A 500 or 503 indicates Rails worker exhaustion or database failure.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-lago-host:3000/api/v1/events.
3. Set Method to POST.
4. Set Expected status code to 200.
5. Under Advanced → Headers, add:
   • Authorization: Bearer YOUR_API_KEY
   • Content-Type: application/json
6. Under Advanced → Body, set body to:

   {"event":{"transaction_id":"vigilmon-probe","external_customer_id":"probe","code":"probe_metric"}}
   

7. Under Advanced → Keyword check, add:
   • Keyword present: ok
8. Set Check interval to 60 seconds.
9. Save the monitor.

A failure here means billable usage events from your product are being lost right now. Every minute of event ingestion downtime represents unrecoverable billing data unless your product buffers and retries at the client side.

Step 3: Monitor the Webhook Delivery Service

Lago delivers payment, invoice, and subscription lifecycle events to your downstream systems via webhooks. If the webhook service fails — due to Sidekiq worker crashes, Redis connection failures, or queue backlog — your CRM, ERP, and payment processor integrations stop receiving billing updates.

Test webhook endpoint health via the Lago admin API:

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  http://your-lago-host:3000/api/v1/webhooks/endpoints \
  | python3 -m json.tool | grep -E "status|url"

A healthy webhook service returns a list of configured webhook endpoints with their delivery status. If the Lago API returns a 500 on this endpoint, the Sidekiq background job system handling webhook delivery is likely failing.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-lago-host:3000/api/v1/webhooks/endpoints.
3. Set Expected status code to 200.
4. Under Advanced → Headers, add:
   • Authorization: Bearer YOUR_API_KEY
5. Under Advanced → Keyword check, add:
   • Keyword present: webhook_endpoints
   • Keyword absent: error
6. Set Check interval to 120 seconds.
7. Save the monitor.

Step 4: Monitor the Invoice Generation Queue

Lago generates invoices asynchronously through a background job queue backed by Sidekiq and Redis. If the invoice generation queue backs up — due to Redis unavailability, a long-running billing computation, or job failures — customers stop receiving invoices even though their subscriptions are active and usage is being metered.

Test invoice generation queue health via the invoices API:

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  http://your-lago-host:3000/api/v1/invoices?per_page=1 \
  | python3 -m json.tool | grep -E "invoices|total_count"

A healthy invoice system returns the most recent invoice list with metadata. If the endpoint returns an empty invoices array when active subscriptions exist, or if a 500 error is returned, the invoice generation pipeline has stalled.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-lago-host:3000/api/v1/invoices?per_page=1.
3. Set Expected status code to 200.
4. Under Advanced → Headers, add:
   • Authorization: Bearer YOUR_API_KEY
5. Under Advanced → Keyword check, add:
   • Keyword present: invoices
   • Keyword absent: error
6. Set Check interval to 300 seconds.
7. Save the monitor.

Step 5: Monitor Database Connectivity

Lago stores all billing data — customers, subscriptions, events, invoices, charges — in PostgreSQL. A database connectivity failure is catastrophic: the Rails API continues returning 200 for health checks from cache, while every actual billing operation silently fails.

Probe database connectivity through the organizations endpoint:

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  http://your-lago-host:3000/api/v1/organizations \
  | python3 -m json.tool | grep -E "name|email"

A healthy response returns your organization configuration from the database. A 500 Internal Server Error or empty response when you have a configured organization indicates the database connection pool is exhausted or PostgreSQL is unreachable.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-lago-host:3000/api/v1/organizations.
3. Set Expected status code to 200.
4. Under Advanced → Headers, add:
   • Authorization: Bearer YOUR_API_KEY
5. Under Advanced → Keyword check, add:
   • Keyword present: organization
   • Keyword absent: error
6. Set Check interval to 300 seconds.
7. Save the monitor.

This endpoint exercises the full database read path — Active Record connection pool, query execution, and JSON serialization — making it the most comprehensive single database health check available without direct DB access.

Step 6: Monitor Subscription Plan Processing

Lago processes subscription lifecycle events — new subscriptions, plan upgrades, downgrades, and cancellations — through an internal state machine. If subscription processing fails, plan changes requested by customers or your product do not take effect, and billing continues at the wrong rate.

Test the subscription processing endpoint:

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  http://your-lago-host:3000/api/v1/subscriptions?per_page=1 \
  | python3 -m json.tool | grep -E "status|plan_code"

A healthy Lago API returns subscription records with their current status. If active subscriptions show pending status for extended periods or the endpoint returns errors, the subscription state machine background jobs have stalled.

Set up the Vigilmon monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to http://your-lago-host:3000/api/v1/subscriptions?per_page=1.
3. Set Expected status code to 200.
4. Under Advanced → Headers, add:
   • Authorization: Bearer YOUR_API_KEY
5. Under Advanced → Keyword check, add:
   • Keyword present: subscriptions
   • Keyword absent: error
6. Set Check interval to 300 seconds.
7. Save the monitor.

Step 7: Alert Channels

Go to Notifications → New Channel in Vigilmon and configure:

• Email — immediate alerts to your billing operations team and on-call engineer
• Webhook — Slack, PagerDuty, or Discord for team-wide visibility into billing infrastructure status

A failing event ingestion alert looks like:

🔴 DOWN: lago-event-ingestion (HTTP monitor)
Expected status 200, got 503 Service Unavailable
Region: EU-Central
Triggered: 2026-07-13 02:51 UTC

When the service recovers:

✅ RECOVERED: lago-event-ingestion
Downtime: 34 minutes

Set critical severity for the API health endpoint and event ingestion monitor — these represent complete billing pipeline failure with direct revenue impact. Set high severity for the webhook delivery and invoice generation monitors. Use warning severity for subscription processing and database connectivity monitors. Enable Alerting → Escalation to page your on-call engineer immediately if the event ingestion endpoint is down — every minute of downtime represents billable usage that cannot be reconstructed unless your product retries at the client side.

What You've Built

| Scenario | How Vigilmon catches it | |---|---| | Rails API process crash | Health endpoint returns non-200 or connection refused | | Event ingestion queue backed up | POST to /api/v1/events returns 422 or 503 | | Sidekiq/Redis failure | Webhook endpoints API returns 500 | | Invoice generation stalled | Invoices API returns error or stale data | | PostgreSQL connection exhausted | Organizations API returns 500 or error body | | Subscription state machine broken | Subscriptions API returns error | | Puma workers exhausted | All endpoints time out simultaneously |

Billing failures are invisible until a customer calls to ask why their invoice is wrong or their subscription didn't update. External monitoring with Vigilmon gives you a real-time signal when your Lago event ingestion pipeline, invoice generation queue, or webhook delivery service breaks — before a billing gap becomes a revenue recognition problem or a customer churn event.

Start monitoring your Lago billing platform today — register free at vigilmon.online.