# QuietPulse — Full Documentation

## Overview

QuietPulse is a heartbeat monitoring service for cron jobs, scheduled tasks, and background workers. It detects silent failures — when a job doesn't run, hangs, or exits unexpectedly — and sends instant Telegram alerts.

## The Problem

Traditional monitoring (uptime checks, log parsing) tells you if your **server** is alive and if a job **tried** to run. It doesn't tell you if the job **actually completed successfully**. Heartbeat monitoring solves this: the job actively reports "I finished" after each run. If the signal doesn't arrive, something went wrong.

## How It Works

```
┌─────────────┐    ✅ "done"     ┌──────────────┐
│  Your Job   │ ──────────────→ │  QuietPulse  │
└─────────────┘                  └──────┬───────┘
                                        │
                             Missed? ────┤
                                        │
                                  🔔 Alert!
```

1. Create a job in the QuietPulse dashboard
2. Get a unique heartbeat URL
3. Add a `curl` call to your script
4. If the heartbeat doesn't arrive → Telegram notification

## Quick Start with Curl

```bash
#!/bin/bash
# backup.sh
/usr/local/bin/run-backup
if [ $? -eq 0 ]; then
  curl -fsS -m 10 --retry 3 "https://quietpulse.xyz/api/heartbeat/your-token-here"
fi
```

Add to crontab:
```cron
0 2 * * * /usr/local/bin/backup.sh
```

If the backup fails or hangs, the curl never fires. QuietPulse detects the missed heartbeat and alerts you.

## Pricing

| Plan    | Max Jobs | Min Interval | Price  |
|---------|----------|-------------|--------|
| FREE    | 2        | 1 hour      | $0     |
| STARTER | 20       | 5 minutes   | $7/mo  |
| UNLIMITED | ∞     | 1 minute    | $25/mo |

## API

### Send heartbeat
```
GET https://quietpulse.xyz/api/heartbeat/<token>
```
- Returns HTTP 200 on success
- Each job has a unique token
- No authentication needed beyond the token

### Webhook Events
- `POST /api/billing/webhook` — NOWPayments IPN handler

## Tech Stack

- **Frontend**: Angular 21 (SSR)
- **Backend**: NestJS
- **ORM**: Prisma
- **Database**: SQLite
- **Notifications**: Telegram Bot API
- **Payments**: NOWPayments (cryptocurrency)
- **Hosting**: DigitalOcean (Frankfurt, $4/mo)

## Integration Examples

### Python
```python
import requests
import subprocess

result = subprocess.run(["./my-script.sh"])
requests.get("https://quietpulse.xyz/api/heartbeat/YOUR_TOKEN", timeout=10)
```

### Node.js
```javascript
const https = require('https');
try {
  // Your job logic here
  https.get("https://quietpulse.xyz/api/heartbeat/YOUR_TOKEN");
} catch (e) {
  console.error('Job failed:', e.message);
}
```

### GitHub Actions
```yaml
- name: Send heartbeat
  run: curl -fsS https://quietpulse.xyz/api/heartbeat/YOUR_TOKEN
```

## Frequently Asked Questions

### What is the difference between uptime monitoring and heartbeat monitoring?
Uptime monitoring checks if your server or endpoint is responding. Heartbeat monitoring checks if your **specific jobs** ran successfully. A server can be up while critical jobs are failing silently.

### How does QuietPulse differ from Dead Man's Switch?
Dead Man's Switch is the concept (alert when expected activity stops). QuietPulse implements this for cron/scheduled jobs with a dashboard, Telegram alerts, and multiple job management.

### Which payment methods are accepted?
NOWPayments (cryptocurrency). This makes QuietPulse accessible to developers in regions without Stripe/PayPal support.

## Use Cases

- **Database backups** — Verify backups run on schedule
- **Data synchronization** — Monitor ETL jobs and API syncs
- **Report generation** — Catch silent failures in scheduled reports
- **Payment reconciliation** — Ensure financial scripts run daily
- **CI/CD pipelines** — Monitor periodic GitHub Actions
- **n8n automation** — Verify scheduled workflows execute

## Links

- Website: https://quietpulse.xyz
- Blog: https://quietpulse.xyz/blog
- Pricing: https://quietpulse.xyz/pricing
- Documentation: https://quietpulse.xyz/docs
- GitHub: https://github.com/vadyak/quietpulse
- Author: Vadyak (https://github.com/vadyak)

## Blog Articles

### Heartbeat Monitoring for Cron Jobs Explained
URL: https://quietpulse.xyz/blog/heartbeat-monitoring-cron-jobs-explained
Explores how heartbeat monitoring works, why it's better than log monitoring, common mistakes, and a real curl implementation example.

### How to Detect if a Cron Job Is Not Running
URL: https://quietpulse.xyz/blog/how-to-detect-if-a-cron-job-is-not-running
Covers why cron logs aren't enough, how to detect missing executions, and production-ready monitoring patterns.

### Cron Job Failed Silently? Here's How to Actually Detect It
URL: https://quietpulse.xyz/blog/cron-job-failed-silently-how-to-detect-it
Details why cron jobs fail silently (OOM, network issues, locked files) and practical detection methods.

### Cron Job Monitoring Best Practices
URL: https://quietpulse.xyz/blog/cron-job-monitoring-best-practices
Production-tested patterns: timeout handling, grace periods, alert routing, and common pitfalls to avoid.

### How to Monitor Cron Jobs (and Stop Silent Failures)
URL: https://quietpulse.xyz/blog/how-to-monitor-cron-jobs-and-stop-silent-failures
Complete guide to heartbeat signals, failure-safe curl patterns, and alerting strategies.

### Telegram Alerts for Cron Job Monitoring
URL: https://quietpulse.xyz/blog/telegram-alerts-for-cron-job-monitoring
Step-by-step guide to connecting Telegram in QuietPulse and receiving missed job alerts.

### GitHub Actions Monitoring
URL: https://quietpulse.xyz/blog/github-actions-monitoring-cron-fail-alerts
How to add heartbeat monitoring to GitHub Actions scheduled workflows with YAML examples.

### Monitor Cron Jobs with n8n and QuietPulse
URL: https://quietpulse.xyz/blog/monitor-cron-jobs-with-n8n-and-quietpulse
Integrating QuietPulse with n8n workflows for automated cron monitoring and alert routing.

### Detect Missed Cron Jobs in Production
URL: https://quietpulse.xyz/blog/detect-missed-cron-jobs-in-production
First article in the series — why traditional monitoring fails for scheduled tasks and how heartbeat monitoring fills the gap.