Reference · Dead-man's switch

Heartbeats

Register a heartbeat for any scheduled job, cron, or batch pipeline outside Landfall — your own job pings a URL every time it runs, and if the ping ever stops arriving, Landfall opens a real incident naming which heartbeat went silent and for how long.

What it is, and what it is not

A heartbeat is ordinary tenant configuration — a name, an expected interval, and a grace period — plus one fact Landfall tracks for you: when it was last pinged. It is not a monitoring agent installed on your infrastructure and it does not run your job for you; it only watches for the ping your own job sends.

Silence detection and incident-opening (the sibling half of this feature, Triggering Integrations → Heartbeats) run on a 5-minute sweep — a heartbeat that goes silent is caught within one sweep interval of crossing its configured interval + grace deadline, not instantly.

What you'll need

An admin on your Landfall organization, to register the heartbeat.
Your organization's trigger ingest token (the same token POST /triggers already uses) — issue one from Settings → Integrations if you don't have one yet.
The ability to add one HTTP call to the end of your scheduled job, cron, or pipeline step.

Registering a heartbeat

Choose a name, an expected interval, and a grace period
The name identifies the heartbeat in incident titles and the heartbeat list — pick something a human recognizes, like nightly-backup or hourly-reconcile. The expected interval is how often your job normally runs; the grace period is extra tolerance on top of that before a missed run is treated as silence (a job that runs "every hour, give or take 10 minutes" is expectedIntervalSeconds: 3600, graceSeconds: 600).
```
POST /o/:slug/heartbeats
Authorization: Bearer <your session token>
Content-Type: application/json

{
  "name": "nightly-backup",
  "expectedIntervalSeconds": 86400,
  "graceSeconds": 1800
}
```
Ping it from the end of your job
Add one HTTP call as the last step of your job — after the real work succeeds, not before. The ping is authenticated with your organization's trigger ingest token, the same credential POST /triggers uses; it is not a new secret to provision.
```
POST /o/:slug/heartbeats/nightly-backup/ping
Authorization: Bearer <your organization's trigger ingest token>
```
A successful ping returns 204 No Content. Repeated pings are always safe — only the most recent one is kept, never a growing history.

The failure response never reveals why

A missing token, a token that belongs to a different organization, and a heartbeat name that doesn't exist all produce the exact same rejection. If a ping is failing, check your token and your heartbeat name together — the response deliberately cannot tell you which one is wrong.

Managing heartbeats

GET /o/:slug/heartbeats lists every registered heartbeat for your organization, including its last-seen time. Any member can read the list; registering, updating the interval/grace, or deleting a heartbeat is admin-gated. A heartbeat's name is fixed once created — renaming is delete and re-register.

Reference

Field	Value
Register / list / read / update / delete	POST / GET / GET :name / PATCH :name / DELETE :name at /o/:slug/heartbeats
Ping	POST /o/:slug/heartbeats/:name/ping, authenticated with your organization's trigger ingest token
Silence sweep interval	Every 5 minutes — see Triggering Integrations → Heartbeats.
Credential	Your organization's existing trigger ingest token — no new secret to provision.