Heartbeat Watches

A Watch is a server-monitored expectation that a worker, cron job, or long-running process will report progress. If the expected signal does not arrive within the configured schedule and grace period, ActionBox creates an ordinary Action for review.

Create with the Python SDK

import os
from actionbox import Actionbox, send_heartbeat

with Actionbox(os.environ["ACTIONBOX_API_KEY"]) as client:
    watch = client.watches.create(
        source_id="src_...",
        name="Nightly backup",
        schedule_type="interval",
        interval_seconds=3600,
        grace_seconds=60,
        signal_method="post",
    )
    heartbeat_url = watch.heartbeat_url
    if heartbeat_url is None:
        raise RuntimeError("ActionBox did not return a heartbeat URL")
    send_heartbeat(heartbeat_url, "start")

Use send_heartbeat for ping, start, success, or fail. It always sends POST.

Capability safety

The raw heartbeat URL is a bearer capability returned only when a Watch is created or its token is rotated.

• Store it in a secret manager.
• Do not log it, place it in source control, or expose it to a browser.
• Prefer signal_method="post" so link previewers cannot record a signal.
• Rotate the token if the capability may have leaked.
• Pause or archive Watches that are no longer expected to report.