Skip to main content

Documentation

Complete guide to setting up website monitoring with PingZen. API documentation, code examples, and best practices.

Heartbeat Monitoring

Heartbeat monitoring is a passive approach: instead of PingZen checking your service, your service tells PingZen "I'm alive" by sending a simple HTTP request. If PingZen doesn't receive a ping within the expected interval, it alerts you.

How It Works

  1. Create a heartbeat monitor in PingZen and get a unique ping URL
  2. Add an HTTP call to the end of your cron job, script, or pipeline
  3. PingZen expects to receive a ping within your configured interval
  4. If a ping is missed (plus grace period), PingZen sends an alert

Use Cases

  • Cron jobs (database backups, log rotation, cleanup scripts)
  • ETL pipelines and data processing jobs
  • Background workers and queue consumers
  • Scheduled reports and email campaigns
  • Deployment scripts and CI/CD pipelines

Ping Signals

PingZen supports multiple signal types for granular job tracking:

Ping (GET)

Simple heartbeat — confirms the job ran

Start

Marks the beginning of a job run

Success

Marks successful completion

Fail

Reports a job failure with optional error details

Integration Examples

Bash / Cron

# Add to the end of your cron job
curl -fsS --retry 3 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG

Python

import requests
requests.get('https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG', timeout=10)

cURL with start/success signals

# Signal job start
curl -fsS https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG/start

# ... your job runs ...

# Signal success
curl -fsS https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG/success

Key Features

  • Unique endpoint URL for each heartbeat monitor
  • Configurable intervals (1 minute to 30 days)
  • Grace period before alerting (up to 24 hours)
  • Start/success/fail signal tracking
  • Full ping history with timestamps and payload data
  • Optional secret authentication via X-Secret header
  • Pause/resume without losing configuration
  • Works with any language or tool that can make HTTP requests

Common Questions

What protocols can I monitor?

PingZen supports 23 protocols: HTTP/HTTPS, WebSocket (WS/WSS), TCP, UDP, ICMP Ping, gRPC, DNS, WHOIS, SSL certificates, Email (SMTP/IMAP/POP3), FTP/FTPS, DNSBL, PageSpeed, SOCKS5, MTProxy, API Check, and Transaction. You can monitor websites, APIs, servers, databases, and any network service.

How fast can I get alerts?

Telegram alerts are delivered within 1-2 seconds of detection. Slack and Discord notifications arrive almost instantly. You can configure multiple alert channels for redundancy.

Can I organize monitors by project?

Yes! PingZen supports workspaces, which let you organize monitors by project, environment, or team. Each workspace can have its own alert configurations and team members.

Is there an API for automation?

Absolutely. PingZen provides a full REST API with OpenAPI documentation. You can create, update, and delete monitors programmatically.

How do status pages work?

Status pages are public, branded pages showing your services' uptime. You can display real-time status and allow customers to subscribe for updates.

What happens if I reach my monitor limit?

We'll notify you when approaching your limit. You can pause some monitors or contact us for increased capacity. We never stop monitoring without warning, ensuring your critical services stay protected.

Ready to stop missing downtime?

Join thousands of teams who trust PingZen. Setup takes 30 seconds.

Start Free