Skip to main content
Heartbeat monitors require an expected interval and grace period. DevHelm generates a unique ping URL that your service calls on each successful run.
Define this in code. YAML format · Terraform

​
Config fields

FieldTypeRequiredDefaultDescription
config.expectedIntervalintegerYes—Expected time between pings in seconds (1–86,400)
config.gracePeriodintegerYes—Extra time to wait before marking as down, in seconds
The total allowed gap between pings is expectedInterval + gracePeriod. For a job that runs hourly with a 10-minute grace period, set expectedInterval: 3600 and gracePeriod: 600.

​
Ping URL

When you create a heartbeat monitor, DevHelm generates a unique pingUrl. The URL is available on the monitor response object. Your service should call this URL (any HTTP method) on each successful run. 
curl -s https://api.devhelm.io/api/v1/heartbeat/<token>

​
Sending payload data

You can include a JSON body with your ping. This is useful for reporting job metadata: 
curl -X POST https://api.devhelm.io/api/v1/heartbeat/<token> \
  -H "Content-Type: application/json" \
  -d '{"records_processed": 1542, "duration_ms": 8300}'
Use the heartbeat_payload_contains assertion to validate payload contents.

​
Assertions

AssertionRequired fieldsDescription
heartbeat_received(none)Passes if a ping was received within the expected window
heartbeat_max_intervalmaxSecondsFails if the actual interval between pings exceeds threshold
heartbeat_interval_driftmaxDeviationPercent (1–100)Fails if the interval varies more than the allowed percentage
heartbeat_payload_containspath, valueFails if the ping payload at the given path doesn’t contain the value

​
Examples

​
Cron job (hourly)

monitors:
  - name: Hourly ETL
    type: HEARTBEAT
    config:
      expectedInterval: 3600
      gracePeriod: 600
    assertions:
      - type: heartbeat_received
        severity: fail

​
With payload validation

monitors:
  - name: Report generator
    type: HEARTBEAT
    config:
      expectedInterval: 86400
      gracePeriod: 3600
    assertions:
      - type: heartbeat_received
        severity: fail
      - type: heartbeat_payload_contains
        path: status
        value: success
        severity: fail
      - type: heartbeat_interval_drift
        maxDeviationPercent: 25
        severity: warn

​
Next steps

Heartbeat overview

When to use heartbeat monitors.

Cron job guide

Patterns for background job monitoring.