Job Monitor Operations

Use a Watch when a worker, cron job, or long-running process must prove that it is alive. ActionBox evaluates the expected schedule and grace period; a missed signal, failed run, or exceeded runtime creates one ordinary Action for human review.

Lifecycle

The API also returns derived running and late values. Treat status and the timestamps in the Watch response as the source of truth, not a dashboard badge or push notification.

Create a Watch

Watch management uses a user session and requires an owner or admin role:

curl -fsS -X POST https://api.actionbox.cloud/v1/watches \
  -H "Authorization: Bearer $ACTIONBOX_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_<source_id>",
    "name": "Nightly backup",
    "schedule_type": "interval",
    "interval_seconds": 3600,
    "grace_seconds": 300,
    "timezone": "UTC",
    "max_runtime_seconds": 7200,
    "priority": "high",
    "signal_method": "post"
  }'

An interval is between 60 seconds and 30 days. A cron schedule uses exactly five valid cron fields and an IANA timezone. Grace and maximum runtime are bounded to 30 days. The response returns a raw heartbeat_url once; store it in the job's secret manager before closing the response.

Send signals

The returned capability URL supports these paths:

For a POST-only Watch, use the CLI wrapper or Python SDK. Both read the capability from your environment rather than putting it in a shell argument:

actionbox run -- /opt/jobs/nightly-backup.sh

For a long-running process, the Python SDK can call send_heartbeat(os.environ["ACTIONBOX_WATCH_URL"], "ping"). Keep transport errors separate from the job's exit status and do not print the URL.

Successful heartbeat requests return 204 with no credential-bearing response. GET is accepted only when signal_method is any; a POST-only Watch returns 405 WATCH_POST_REQUIRED. Do not add arbitrary metadata to a heartbeat. The schedule, timestamps, and signal type are the durable health record.

Incidents and recovery

The evaluator considers a Watch late after the expected occurrence plus grace_seconds, or when max_runtime_seconds is exceeded for an active run. It creates one deduplicated ordinary Action and links it through incident_action_id. Repeated evaluator passes do not create a second Action.

When a healthy signal arrives, ActionBox system-resolves the open incident. A human-resolved incident is not reopened while the Watch remains in the same down episode, including when another failure signal arrives. A later ping or success records recovery and returns the Watch to healthy; the recovered Watch clears incident_action_id, and the next failure starts a new incident Action. This prevents one continuing outage from producing an alert storm. If a failure is expected, pause the Watch before maintenance; paused signals are recorded but do not evaluate the schedule or create Actions.

Where configured for a Business or Enterprise workspace, a monitor can add one Retry job control to future incidents. A reviewer requests the retry; your HTTPS receiver verifies the signed callback with that Source's webhook signing secret, deduplicates its request ID, and decides how to run the job. A Source created in the monitor setup does not reveal its signing secret there; rotate and save it from the Source screen before deploying a receiver. The control is not proof that the retry succeeded. Report a genuine success signal after validating the job's result. Changing the profile does not rewrite an incident that is already open.

Management endpoints

A Source key can manage only its own active Watches through /v1/source/watches and the corresponding pause, resume, rotate, and archive routes. Source-scoped creation keeps the source_id equal to the authenticated Source. A Watch capability URL is not a user session and cannot list or edit a Watch.

Capability safety

• Keep the heartbeat URL in a secret manager; never put it in logs, source control, issue attachments, browser code, or a referrer.
• Prefer signal_method: "post" so link scanners and previewers cannot record a GET signal.
• Rotate the capability immediately after a suspected disclosure and update the job. The old URL stops working after rotation.
• Archive a Watch that is no longer expected to run. Revoking its Source also pauses the Watch and invalidates its heartbeat capability.
• Use the Watch event history for diagnosis; do not infer health from a missing notification.

Common issues