Drumbeats logo
Drumbeats
Reference

Ping Events

Drumbeats has four named ping events — start, success, failure, log — plus the exit-code shorthand. Each ping costs 1 Beat. This page is the semantic reference.

A Drumbeats ping is a single HTTP request to the monitor's URL — https://api.drumbeats.io/v1/ping/<monitor-id>/<event>. The event suffix is one of four named values (start, success, failure, log) or an exit-code shorthand (/0, /1, …). Every ping costs 1 Beat plus any payload overhead. This page is the semantic reference: what each event signals, when to use it, and how the monitor reacts.

For the HTTP-level reference see Ping API; for the per-pattern flow see Status signals.

The four named events

EventMeaningMonitor effect
startThe job has begun.Opens a run on the timeline. Unlocks duration tracking and hung-run detection. Optional for Cron / Heartbeat monitors, required for Event-driven monitors so run_id correlation works.
successThe job finished cleanly.Closes the run; resolves any open incident on the monitor. The monitor flips back to UP.
failureThe job failed.Closes the run; failure counter +1. Opens an incident once failure_tolerance is exceeded.
logProgress note.Recorded on the timeline next to the run's start / finish pings (when run_id matches). Does not change monitor status.

Core flows

Cron or scheduled job

start is optional for scheduled jobs; success / failure is the minimum useful pair.

bash
# Start is optional; success/failure is required for explicit failure tracking.
/usr/bin/backup.sh && status=success || status=failure
curl https://api.drumbeats.io/v1/ping/<monitor-id>/$status
# Start is optional; success/failure is required for explicit failure tracking.
/usr/bin/backup.sh && status=success || status=failure
curl https://api.drumbeats.io/v1/ping/<monitor-id>/$status

The exit-code shorthand collapses the same flow to one line — see Exit codes.

Event-driven or worker job

start with a run_id is required so Drumbeats can pair the finish ping back to the right run when multiple workers run concurrently.

bash
RUN_ID="job-$(date +%s)-$$"
curl "https://api.drumbeats.io/v1/ping/<monitor-id>/start?run_id=$RUN_ID"
node process-order.js
EXIT=$?
if [ $EXIT -eq 0 ]; then
  curl "https://api.drumbeats.io/v1/ping/<monitor-id>/success?run_id=$RUN_ID"
else
  curl "https://api.drumbeats.io/v1/ping/<monitor-id>/failure?run_id=$RUN_ID"
fi
RUN_ID="job-$(date +%s)-$$"
curl "https://api.drumbeats.io/v1/ping/<monitor-id>/start?run_id=$RUN_ID"
node process-order.js
EXIT=$?
if [ $EXIT -eq 0 ]; then
  curl "https://api.drumbeats.io/v1/ping/<monitor-id>/success?run_id=$RUN_ID"
else
  curl "https://api.drumbeats.io/v1/ping/<monitor-id>/failure?run_id=$RUN_ID"
fi

Adding logs mid-run

log pings attach context without changing status. Useful for multi-phase jobs where you want to see which phase actually failed.

bash
curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/log \
  -H "Content-Type: application/json" \
  -d '{"message":"50% complete","step":"import-users"}'
curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/log \
  -H "Content-Type: application/json" \
  -d '{"message":"50% complete","step":"import-users"}'

Status rules in plain language

  • The latest success or failure defines the run's final status.
  • A start with no follow-up before max_duration_seconds is a hung run, treated as a failure.
  • log never changes status. Multiple log pings per run are fine — each costs 1 Beat.
  • failure does not page the team on its own; the notification group is paged once failure_tolerance is exceeded (default 1).

For the alerting side of these rules — failure_tolerance, schedule_tolerance, alert_surge_threshold, recovery messages — see Alert logic.