Uptime monitoring for Killbill subscription billing platform

Killbill is the financial backbone of your subscription business. When your billing platform goes down — even briefly — subscription renewals fail, payment retries stall, and revenue recognition breaks. Because Killbill runs as a background service rather than a customer-facing app, outages often go undetected until a customer calls to say their subscription was cancelled unexpectedly.

This tutorial covers production-grade uptime monitoring for Killbill using Vigilmon. We will walk through:

• Monitoring the Killbill /1.0/kb/nodesInfo health endpoint
• Monitoring the Kaui web UI availability
• Database connectivity checks
• SSL certificate alerts
• Heartbeat monitoring for scheduled billing jobs

Prerequisites

• Killbill running (bare metal, Docker, or Kubernetes) with the REST API accessible
• Kaui admin UI deployed and reachable
• A free account at vigilmon.online

Part 1: Understand the Killbill health endpoints

Killbill exposes a REST API on port 8080 by default. The most useful health endpoint for external monitoring is:

GET /1.0/kb/nodesInfo

This returns a JSON array describing each node in the Killbill cluster — version, plugin status, and node state. A healthy single-node deployment returns HTTP 200 with a response like:

[
  {
    "nodeName": "killbill-node-1",
    "bootTime": "2026-07-01T00:00:00.000Z",
    "lastUpdatedDate": "2026-07-12T08:00:00.000Z",
    "kbVersion": "0.24.0",
    "apiVersion": "0.54.0",
    "pluginsInfo": []
  }
]

If Killbill is starting up, the API is unavailable, or a required plugin failed to load, the endpoint returns 500 or times out. This makes it the correct target for uptime monitoring.

Verify the endpoint manually

curl -u admin:password \
  -H "X-Killbill-ApiKey: bob" \
  -H "X-Killbill-ApiSecret: lazar" \
  http://localhost:8080/1.0/kb/nodesInfo

If you have not changed the default credentials, admin/password with API key bob and secret lazar are the out-of-the-box values used in development. Change these in production and store them in a secrets manager.

Part 2: Expose the health endpoint for external monitoring

Killbill's API port (8080) is typically not exposed to the public internet. You have two options:

Option A — reverse proxy with a read-only health route

Place Nginx in front of Killbill and expose only the health path:

# /etc/nginx/sites-available/killbill-health
server {
    listen 443 ssl;
    server_name billing.example.com;

    ssl_certificate     /etc/letsencrypt/live/billing.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/billing.example.com/privkey.pem;

    # Only allow the health check path
    location = /1.0/kb/nodesInfo {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header X-Killbill-ApiKey  "bob";
        proxy_set_header X-Killbill-ApiSecret "lazar";
        proxy_set_header Authorization "Basic YWRtaW46cGFzc3dvcmQ=";
    }

    # Block everything else
    location / {
        return 403;
    }
}

This lets Vigilmon reach https://billing.example.com/1.0/kb/nodesInfo without exposing the full API.

Option B — Docker network with a dedicated health container

If you run Killbill in Docker Compose, add a minimal health-proxy sidecar:

# docker-compose.yml
services:
  killbill:
    image: killbill/killbill:0.24.0
    environment:
      KILLBILL_DAO_URL: jdbc:mysql://db:3306/killbill
    networks:
      - internal

  health-proxy:
    image: nginx:alpine
    volumes:
      - ./nginx-health.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "8081:80"
    networks:
      - internal

networks:
  internal:

Part 3: Set up HTTP monitoring in Vigilmon

Monitor the nodesInfo health endpoint

1. Log in to vigilmon.online and click Add Monitor.
2. Choose HTTP(S) monitor.
3. Enter: https://billing.example.com/1.0/kb/nodesInfo
4. Set interval to 1 minute.
5. Add a keyword check: must contain kbVersion.
6. Under Custom headers, add any required auth headers if not handled by your proxy.
7. Add your alert channel (email, Slack, or webhook).
8. Click Save.

The keyword kbVersion confirms the Killbill node API responded correctly. A proxy error page or an empty response would not contain this string, so you avoid false positives from intermediate load balancers.

Monitor the Kaui admin UI

Kaui is the Ruby on Rails admin interface for Killbill. Monitor it separately because Kaui and Killbill are independent processes — one can be down while the other is up:

1. Click Add Monitor.
2. Choose HTTP(S) monitor.
3. Enter: https://kaui.example.com/ (or whatever URL your Kaui deployment uses).
4. Set interval to 1 minute.
5. Add a keyword check: must contain Kaui or another string from your login page.
6. Click Save.

Monitor database connectivity

Killbill requires MySQL or PostgreSQL to function. Add a database connectivity check using Killbill's own API, which fails fast when the database is unreachable:

GET /1.0/kb/test/db_connectivity

This endpoint returns HTTP 200 when the database is reachable and HTTP 500 when it is not. Add a second Vigilmon HTTP monitor for this path to separate DB failures from application failures.

Part 4: SSL certificate monitoring

Killbill handles billing data. Expired certificates cause payment SDKs to reject connections and break checkout flows before a browser warning ever appears.

1. In Vigilmon, click Add Monitor.
2. Choose SSL monitor.
3. Enter each domain:
   • billing.example.com (Killbill API)
   • kaui.example.com (Kaui admin UI)
4. Set alert threshold to 30 days before expiry — billing integrations often have longer propagation cycles than web apps.
5. Add your alert channel.

Part 5: Heartbeat monitoring for scheduled billing jobs

Killbill runs scheduled jobs for invoice generation, payment retries, dunning logic, and subscription renewals. These jobs produce side effects (charges, emails, cancellations) but do not expose a health endpoint you can poll. Use Vigilmon heartbeats to verify they run.

How Vigilmon heartbeats work

A heartbeat monitor expects a ping at a defined interval. If the ping does not arrive within the grace period, Vigilmon fires an alert. This turns a silent cron failure into a paged incident.

Set up a heartbeat monitor

1. In Vigilmon, click Add Monitor.
2. Choose Heartbeat monitor.
3. Name it Killbill Invoice Job (or whatever job you are monitoring).
4. Set interval to 24 hours (daily) with a 2-hour grace period.
5. Copy the unique heartbeat URL, e.g.: https://hb.vigilmon.online/ping/abc123
6. Click Save.

Wire the heartbeat into your billing job

If you trigger billing jobs via a script or cron:

#!/bin/bash
# /opt/killbill/run-invoice-job.sh

# Trigger Killbill invoice generation via API
curl -s -u admin:password \
  -H "X-Killbill-ApiKey: bob" \
  -H "X-Killbill-ApiSecret: lazar" \
  -X POST \
  http://localhost:8080/1.0/kb/invoices

# Notify Vigilmon that the job completed successfully
curl -s https://hb.vigilmon.online/ping/abc123

If you trigger jobs via Killbill's built-in Quartz scheduler, add a plugin that fires the heartbeat ping on job completion:

// KillbillActivator.java (plugin entry point)
@Override
public void start() throws Exception {
    scheduler.scheduleJob(
        JobBuilder.newJob(InvoiceHeartbeatJob.class)
            .withIdentity("invoiceHeartbeat", "killbill")
            .build(),
        TriggerBuilder.newTrigger()
            .withSchedule(CronScheduleBuilder.cronSchedule("0 0 2 * * ?"))
            .build()
    );
}

// InvoiceHeartbeatJob.java
public class InvoiceHeartbeatJob implements Job {
    @Override
    public void execute(JobExecutionContext context) throws JobExecutionException {
        // Run your invoice logic here
        runInvoiceGeneration();

        // Ping Vigilmon on success
        try {
            new URL("https://hb.vigilmon.online/ping/abc123").openStream().close();
        } catch (IOException e) {
            log.warn("Failed to ping heartbeat monitor", e);
        }
    }
}

Part 6: Webhook alerts

Add a webhook receiver to your infrastructure to receive Vigilmon DOWN/UP events and route them to your on-call rotation or incident management system:

// webhook-receiver.ts
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook/vigilmon', (req, res) => {
  const { monitor_name, status, url, response_code, checked_at } = req.body;

  if (status === 'down') {
    console.error('[VIGILMON] Killbill monitor DOWN', {
      monitor: monitor_name,
      url,
      code: response_code,
      at: checked_at,
    });

    // Stop scheduled billing operations if the API is unreachable
    pauseBillingJobs();

    // Page on-call team
    notifyOnCall({ monitor: monitor_name, url });
  } else if (status === 'up') {
    console.info('[VIGILMON] Killbill monitor recovered', { monitor: monitor_name });
    resumeBillingJobs();
  }

  res.sendStatus(204);
});

Vigilmon sends this payload on DOWN and UP transitions:

{
  "monitor_id": "mon_abc123",
  "monitor_name": "Killbill nodesInfo",
  "status": "down",
  "url": "https://billing.example.com/1.0/kb/nodesInfo",
  "checked_at": "2026-07-12T08:01:00Z",
  "response_code": 503,
  "response_time_ms": 2041
}

Summary

Your Killbill deployment now has five layers of monitoring:

1. /1.0/kb/nodesInfo endpoint — confirms Killbill nodes are alive and reporting correctly, polled every minute.
2. Kaui admin UI monitor — catches Kaui failures independently of the Killbill API.
3. Database connectivity monitor — isolates DB failures from application failures.
4. SSL monitors — alerts 30 days before certificates expire on billing and admin domains.
5. Heartbeat monitors — detect silently failed invoice, retry, and dunning jobs before customers are affected.

Vigilmon handles check scheduling, multi-region polling, alert routing, and uptime history. You get notified within 60 seconds of any failure at the API, UI, database, or certificate layer.

Monitor your Killbill billing platform free at vigilmon.online

#killbill #billing #monitoring #payments #devops