Quick Start Guide

Get started with DeadManPing in 2 minutes. Monitor your cron jobs with a simple curl command.

Important: What DeadManPing Does

DeadManPing doesn't run your jobs. It only observes the results.

Your cron runs your jobs. Your scripts execute your logic. DeadManPing only observes if the ping arrived, when it arrived, and what payload it contained.

Keep your cron. Keep your scripts. Just add one curl line at the end of your existing script.

1. Create a Monitor

After signing up, create your first monitor. Give it a name and set how often your job should run.

2. Get Your Ping URL

Each monitor gets a unique URL. Copy it and add it to your cron job or script.

https://deadmanping.com/api/ping/your-monitor-slug

3. Add to Your Existing Script

Important: The curl command must be inside your script, not in the cron line, because only in the script do you have access to variables from execution results (e.g., count, file size, duration).

Here are examples for different scenarios:

Basic Bash Script

Simple ping to confirm execution

#!/bin/bash
# Your existing backup script here
./backup.sh

# Add this one line at the end
curl -X POST "https://deadmanping.com/api/ping/your-monitor-slug"

Bash Script with Payload

Send data from execution for validation

#!/bin/bash
users_synced=$(./sync_users_logic.sh)
EXIT_CODE=$?

# Ping with data from execution
# In DeadManPing panel: set validation rules like "count >= 100" and "exit_code == 0"
curl -X POST "https://deadmanping.com/api/ping/your-monitor-slug?count=$users_synced&exit_code=$EXIT_CODE"

Crontab Entry

Just call your script. The curl is inside the script.

0 3 * * * /path/to/backup.sh

Python Script

Send file size for backup validation

import os
import subprocess
import requests

# Your existing script logic here
backup_file = "/backups/db-backup.sql"
subprocess.run(["pg_dump", "mydb"], stdout=open(backup_file, "w"))

# Get file size and ping
file_size = os.path.getsize(backup_file) if os.path.exists(backup_file) else 0
# In DeadManPing panel: set validation rule "size > 0"
requests.post(f"https://deadmanping.com/api/ping/your-monitor-slug?size={file_size}")

Node.js Script

Send count of processed records

const https = require('https');

// Your existing script logic here
const recordsSynced = await syncUsers();

// Ping with count
// In DeadManPing panel: set validation rule "count >= 1"
https.request(`https://deadmanping.com/api/ping/your-monitor-slug?count=${recordsSynced}`, {
  method: 'POST'
}).end();

More Examples

Need more examples? Check out our comprehensive collection with 20+ ready-to-use scripts in Bash, Python, and Node.js:

View All Examples on GitHub

Four Monitoring Methods

DeadManPing supports four monitoring methods. Choose the one that fits your needs:

Simple Ping

Just verify that your job executed. One curl line confirms completion. Perfect for basic monitoring when you only need to know if the cron ran.

How it works: When your job completes, it sends a ping to DeadManPing. If the ping doesn't arrive within the expected time window, you get an alert. The monitor status changes from "healthy" to "late" or "down" if no ping is received.

Bash Example:

#!/bin/bash
./backup.sh

# Simple ping - just confirms execution
curl https://deadmanping.com/api/ping/your-slug

Python Example:

import requests

# Your job logic
backup_database()

# Simple ping
requests.post("https://deadmanping.com/api/ping/your-slug")

Supported HTTP methods: GET, POST, HEAD. All methods work the same way.

Ping with Payload

Verify correctness. Send data from execution and validate results in the dashboard. Configure validation rules to check if results meet your criteria (e.g., count > 100, file_size > 0).

How it works: Send data in query parameters (GET) or JSON body (POST). DeadManPing validates the payload against rules you configure in the dashboard. If validation fails, the monitor status changes to "failed" and you get an alert. Only fields declared in your validation rules are checked - extra fields are ignored.

Bash Example (Query Parameters):

#!/bin/bash
users_synced=$(./sync_users.sh)
EXIT_CODE=$?

# Ping with payload via query parameters
# In DeadManPing panel: set validation rules like "count >= 100" and "exit_code == 0"
curl -X POST "https://deadmanping.com/api/ping/your-slug?count=$users_synced&exit_code=$EXIT_CODE"

Python Example (JSON Body):

import requests

# Your job logic
records_synced = sync_users()
backup_size = get_backup_size()

# Ping with payload via JSON body
# In DeadManPing panel: set validation rules like "count >= 100" and "size > 0"
requests.post(
  "https://deadmanping.com/api/ping/your-slug",
  json={"count": records_synced, "size": backup_size}
)

Payload format: Query parameters (GET/HEAD) or JSON body (POST). Max payload size: 2KB. Validation rules can use operators: ==, !=, >, <, >=, <=, contains, starts_with, ends_with.

Start/Stop Tracking

Measure execution time. Track job duration and optionally include payload validation. Perfect for tracking job duration and detecting performance issues.

How it works: Send a POST request to /api/ping/your-slug/start at the beginning of your job. This returns a run_id. When your job completes, send a ping with the run_id as a query parameter. DeadManPing automatically calculates the duration between start and stop. The duration is displayed in the dashboard and can be used for performance monitoring.

Bash Example:

#!/bin/bash

# Start tracking - returns run_id
RUN_ID=$(curl -s -X POST "https://deadmanping.com/api/ping/your-slug/start" \
  -H "Content-Type: application/json" | jq -r '.run_id')

# Your job logic
./backup.sh
EXIT_CODE=$?

# Stop tracking with run_id
# Duration is automatically calculated and displayed in dashboard
curl -X POST "https://deadmanping.com/api/ping/your-slug?run_id=$RUN_ID"

Python Example:

import requests

# Start tracking
start_response = requests.post("https://deadmanping.com/api/ping/your-slug/start")
run_id = start_response.json()["run_id"]

# Your job logic
sync_users()

# Stop tracking
# Duration is automatically calculated: stop_time - start_time
requests.post(f"https://deadmanping.com/api/ping/your-slug?run_id={run_id}")

Duration tracking: The dashboard automatically calculates execution time in milliseconds. If a job run is not completed (no stop ping), it remains in "running" status. You can optionally provide your own run_id in the start request body.

Start/Stop with Payload

Track duration and validate payload data for complete monitoring. Combines execution time tracking with payload validation.

How it works: Same as Start/Stop Tracking, but include payload data in the stop ping. DeadManPing tracks both execution duration and validates the payload against your rules. This gives you complete visibility: you know how long the job took AND whether the results are correct.

Bash Example:

#!/bin/bash

# Start tracking
RUN_ID=$(curl -s -X POST "https://deadmanping.com/api/ping/your-slug/start" \
  -H "Content-Type: application/json" | jq -r '.run_id')

# Your job logic
users_synced=$(./sync_users.sh)
EXIT_CODE=$?

# Stop tracking with run_id AND payload
# Duration is tracked AND payload is validated
curl -X POST "https://deadmanping.com/api/ping/your-slug?run_id=$RUN_ID&count=$users_synced&exit_code=$EXIT_CODE"

Python Example:

import requests

# Start tracking
start_response = requests.post("https://deadmanping.com/api/ping/your-slug/start")
run_id = start_response.json()["run_id"]

# Your job logic
records_synced = sync_users()
backup_size = get_backup_size()

# Stop tracking with run_id AND payload
# Duration is tracked AND payload is validated
requests.post(
  f"https://deadmanping.com/api/ping/your-slug?run_id={run_id}",
  json={"count": records_synced, "size": backup_size}
)

Best of both worlds: You get execution duration tracking AND payload validation. If validation fails, the job run is marked as "failed" even if the duration was normal. This helps detect jobs that complete but produce incorrect results.

API Reference

Detailed technical documentation for all API endpoints and how they work.

1. Simple Ping Endpoint

Endpoint:

GET|POST|HEAD https://deadmanping.com/api/ping/{slug}

Description:

Sends a ping to confirm job execution. Updates monitor status to "healthy" and sets the next expected ping time.

Response (200 OK):

{
  "ok": true,
  "monitor": "Backup Daily",
  "status": "healthy"
}

How it works:

Updates last_ping_at timestamp
Calculates next_expected_ping_at based on expected interval + grace period
Changes status from "pending" → "healthy" (first ping) or "late"/"failed" → "healthy" (recovery)
Creates a ping record in the database
Triggers recovery alerts if status changed from failed/late to healthy

2. Ping with Payload Endpoint

Endpoint:

POST https://deadmanping.com/api/ping/{slug}?field1=value1&field2=value2
POST https://deadmanping.com/api/ping/{slug}
Content-Type: application/json

{"field1": "value1", "field2": "value2"}

Description:

Sends a ping with payload data for validation. Only fields declared in your validation rules are checked - extra fields are ignored.

Payload Format:

Query parameters (GET/POST): ?count=100&exit_code=0
JSON body (POST): {"count": 100, "exit_code": 0}
Max size: 2KB total
Supported types: strings, numbers, booleans

How Validation Works:

Extract only declared fields from payload (ignore everything else)
Validate each field against its rule (==, !=, >, <, >=, <=, contains, etc.)
If any field with severity "error" fails → status = "failed"
If only fields with severity "warn" fail → status stays "healthy" but ping shows as "fail"
If all validations pass → status = "healthy"

Response (200 OK):

{
  "ok": true,
  "monitor": "Backup Daily",
  "status": "healthy"  // or "failed" if validation failed
}

3. Start Tracking Endpoint

Endpoint:

POST https://deadmanping.com/api/ping/{slug}/start
Content-Type: application/json

{
  "run_id": "optional-custom-run-id",  // Optional
  "metadata": {}  // Optional
}

Description:

Starts tracking a job run. Returns a run_id that you must include in the stop ping. If you don't provide a run_id, one is automatically generated.

Response (200 OK):

{
  "ok": true,
  "run_id": "550e8400-e29b-41d4-a716-446655440000"
}

How it works:

Creates a job run record with status "running"
Stores started_at timestamp
Returns run_id that you must use in the stop ping
If you provide a custom run_id, it must be unique for this monitor

4. Stop Tracking (with run_id)

Endpoint:

POST https://deadmanping.com/api/ping/{slug}?run_id={run_id} POST https://deadmanping.com/api/ping/{slug}?run_id={run_id}&count=100&exit_code=0

Description:

Completes a job run started with the start endpoint. Automatically calculates duration. Optionally includes payload for validation.

How Duration is Calculated:

Duration = stop_time - start_time (in milliseconds)
Stored in job_runs.duration_ms
Also stored in pings.duration_ms for the ping record
Displayed in dashboard for performance monitoring

Job Run Status:

"completed": If payload validation passes (or no validation rules)
"failed": If payload validation fails
"running": If stop ping never arrives (job crashed or timed out)

Response (200 OK):

{
  "ok": true,
  "monitor": "Backup Daily",
  "status": "healthy"
}

Error Responses

404 - Monitor Not Found:

{
  "error": "Monitor not found"
}

403 - Monitor Paused or Subscription Expired:

{
  "error": "Monitor is paused. Please upgrade your plan to reactivate it."
}

429 - Rate Limit Exceeded:

{
  "error": "Rate limit exceeded"
}

Max 1 ping per 10 seconds per monitor. This prevents accidental spam and ensures accurate monitoring.

400 - Invalid Payload:

{
  "error": "Payload too large (max 2KB)",
  "details": "..."
}

Monitor Status Lifecycle

Status States:

"pending": Monitor created but no ping received yet
"healthy": Pings arriving on time and validation passing
"late": Ping received but after expected time window
"failed": Ping received but payload validation failed (error severity)
"down": No ping received within expected time + grace period
"paused": Monitor disabled (subscription expired or manually paused)

Status Transitions:

pending → healthy (first successful ping)
healthy → late (ping received but too late)
healthy → failed (ping received but validation failed)
healthy → down (no ping received)
late → healthy (ping received on time)
late → down (no ping received)
failed → healthy (ping received with valid payload)
down → healthy (ping received after downtime)
down → late (ping received but late)

Alert Triggers:

Failure alert: When status changes to "failed" or "down"
Recovery alert: When status changes from "failed"/"late"/"down" to "healthy"
Alerts are sent via email, Slack, or Discord webhooks (configured in settings)

What Can You Monitor?

DeadManPing can monitor different types of verification with data from your script execution:

File Verification

Check if backup file exists and size (GB)

if [ -f "$BACKUP_FILE" ]; then
  FILE_SIZE_GB=$(du -h "$BACKUP_FILE" | ...)
  curl -X POST "https://deadmanping.com/api/ping/your-slug?file_exists=1&size_gb=$FILE_SIZE_GB"
fi

Count Verification

How many records/items were processed

RECORDS_PROCESSED=$(./sync.sh | grep -c "synced")
curl -X POST "https://deadmanping.com/api/ping/your-slug?count=$RECORDS_PROCESSED"

Duration Verification

How long script execution took

START_TIME=$(date +%s)
./generate_report.sh
END_TIME=$(date +%s)
DURATION=$((END_TIME - START_TIME))
curl -X POST "https://deadmanping.com/api/ping/your-slug?duration_seconds=$DURATION"

Status Verification

Success/failure with context

./backup.sh
EXIT_CODE=$?
SIZE=$(stat -f%z "$BACKUP_FILE" 2>/dev/null || stat -c%s "$BACKUP_FILE")

# Always ping with exit code and size
# In DeadManPing panel: set validation rules "exit_code == 0" and "size > 0"
curl -X POST "https://deadmanping.com/api/ping/your-slug?exit_code=$EXIT_CODE&size=$SIZE"

Threshold Verification

Numeric values (more/less than X)

FILES_DELETED=$(./cleanup.sh | wc -l)
curl -X POST "https://deadmanping.com/api/ping/your-slug?files_deleted=$FILES_DELETED"
# In dashboard: files_deleted >= 10 → OK, < 10 → WARN

4. Payload Validation

Instead of checking conditions in your code, send data in the payload and configure validation rules in the DeadManPing panel. For example, to detect empty backup files:

curl -X POST "https://deadmanping.com/api/ping/your-monitor-slug?size=$FILE_SIZE"

Then in the DeadManPing panel, set a validation rule: size > 0. The panel will automatically detect violations and alert you.

5. Set Up Alerts

Configure email, Slack, or Discord webhooks in your settings. You'll get instant notifications when:

Your job doesn't ping within the expected time window
Your job reports a failure status
Your job recovers after being down

Have More Questions?

Check out our comprehensive FAQ page for answers to common questions about DeadManPing, monitoring setup, pricing, and more.

Start Monitoring Your Backups

DeadManPing provides automated backup monitoring with dead man switch technology. Set up monitoring in 2 minutes, works with any backup method, and sends alerts via email, Slack, or Discord.