Reference

Status Signals

Drumbeats accepts two equivalent ways to signal job state — named events (start/success/failure/log) and exit-code pings. Reference and decision matrix.

Drumbeats accepts two equivalent ways for a job to signal its state to a monitor: named events and exit-code pings. Both flip the monitor between UP and DOWN; named events also give you progress logs, duration tracking, and concurrency-safe run_id correlation. This page is the side-by-side reference.

Named events

The Drumbeats Ping API defines four named events: start, success, failure, and log. Each maps to a URL suffix on the per-monitor endpoint.

curl https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl https://api.drumbeats.io/v1/ping/<monitor-id>/start
your_job
curl https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl https://api.drumbeats.io/v1/ping/<monitor-id>/start
your_job
curl https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl https://api.drumbeats.io/v1/ping/<monitor-id>/start
your_job || {
  curl https://api.drumbeats.io/v1/ping/<monitor-id>/failure
  exit 1
}
curl https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl https://api.drumbeats.io/v1/ping/<monitor-id>/start
your_job || {
  curl https://api.drumbeats.io/v1/ping/<monitor-id>/failure
  exit 1
}
curl https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl https://api.drumbeats.io/v1/ping/<monitor-id>/start
python extract.py
curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/log \
  -H "Content-Type: application/json" \
  -d '{"payload":"Extract done"}'
python transform.py
curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/log \
  -H "Content-Type: application/json" \
  -d '{"payload":"Transform done"}'
python load.py
curl https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl https://api.drumbeats.io/v1/ping/<monitor-id>/start
python extract.py
curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/log \
  -H "Content-Type: application/json" \
  -d '{"payload":"Extract done"}'
python transform.py
curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/log \
  -H "Content-Type: application/json" \
  -d '{"payload":"Transform done"}'
python load.py
curl https://api.drumbeats.io/v1/ping/<monitor-id>/success

Event semantics

Event	Meaning	Monitor effect
`start`	The job has begun.	Opens a run on the timeline. Optional for Cron monitors, required for Event-driven monitors.
`success`	The job finished cleanly.	Closes the run; resolves any open incident on the monitor.
`failure`	The job failed.	Closes the run; failure counter +1, opens an incident once `failure_tolerance` is exceeded.
`log`	Progress note.	Recorded on the timeline; does not change monitor status or affect incidents.

Exit-code pings

The exit-code form lets a shell script wire itself in with one extra line. Drumbeats maps 0 to success and any value from 1 to 255 to failure, preserving the exact code for debugging.

your_job
curl https://api.drumbeats.io/v1/ping/<monitor-id>/$?

your_job
curl https://api.drumbeats.io/v1/ping/<monitor-id>/$?

your_job
EXIT_CODE=$?
curl https://api.drumbeats.io/v1/ping/<monitor-id>/$EXIT_CODE

your_job
EXIT_CODE=$?
curl https://api.drumbeats.io/v1/ping/<monitor-id>/$EXIT_CODE

See Exit codes for the full mapping table, concurrency-safe variants, and the run_id composition pattern.

When to use which

Use named events when:

The job has a start and a finish you can wrap separately (duration tracking).
You want log pings to record progress through multi-phase jobs.
The job is event-driven and you need run_id correlation across concurrent workers.
You want to attach a payload (stdout, error message) on failure without script gymnastics.

Use exit-code pings when:

The whole job is one shell command and $? is already there.
You want the minimum integration surface — one extra curl line at the end.
The script does not need progress logs, duration tracking, or run_id correlation.

Event-driven jobs with `run_id`

Both signal styles compose with run_id correlation. The pattern below is the event-driven worker shape that combines start (named event) with exit-code finish:

RUN_ID="job-$(uuidgen)"
curl "https://api.drumbeats.io/v1/ping/<monitor-id>/start?run_id=$RUN_ID"
python worker.py
EXIT_CODE=$?
curl "https://api.drumbeats.io/v1/ping/<monitor-id>/${EXIT_CODE}?run_id=$RUN_ID"

RUN_ID="job-$(uuidgen)"
curl "https://api.drumbeats.io/v1/ping/<monitor-id>/start?run_id=$RUN_ID"
python worker.py
EXIT_CODE=$?
curl "https://api.drumbeats.io/v1/ping/<monitor-id>/${EXIT_CODE}?run_id=$RUN_ID"

See Event-driven pings for the full pattern, including hung-run detection and try / finally idioms in Python, Node.js, Go, and PHP.

URL formats

Ping API reference — base URL, parameters, response shapes.
Scheduled pings — the Cron / Heartbeat pattern.
Event-driven pings — the queue-worker / webhook pattern.
Exit codes — full mapping table and concurrency notes.
Payloads — attaching context to any event.