On-call integrations

Heartbeat monitoring

Get paged when a cron job, backup or worker stops checking in.

Start with a test incident API key. Test heartbeats open test incidents, which never call an email, SMS, voice or chat provider.

Create a heartbeat

Use a key with incidents:ingest and incidents:write. Choose how often the job runs and how late it may be. The response includes the heartbeat's ping_url.

curl -X POST https://api.transmit.dev/v1/heartbeats \
  -H "Authorization: Bearer $TRANSMIT_INCIDENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"nightly-backup","configurationId":"00000000-0000-4000-8000-000000000001","escalationPolicyId":"00000000-0000-4000-8000-000000000002","intervalSeconds":86400,"graceSeconds":1800}'

Ping it from the job

# last line of the job, so it only runs on success
curl -fsS -X POST https://api.transmit.dev/v1/heartbeats/00000000-0000-4000-8000-000000000003/ping \
  -H "Authorization: Bearer $TRANSMIT_INCIDENT_KEY"

How it pages

  • A new heartbeat waits for its first ping, so it never pages before the job has run once.
  • When intervalSeconds plus graceSeconds pass without a ping, Transmit opens one high-severity incident on the escalation policy, within about a minute.
  • The next ping resolves that incident and cancels pending escalation. It will not page again until the job has checked in and then missed another deadline.
  • Missed-heartbeat incidents are raised as the key that created the heartbeat. Revoking that key stops the pages, so use a dedicated key.

List heartbeats with GET /v1/heartbeats and remove one with DELETE /v1/heartbeats/ID. Each on-call configuration page shows its heartbeats and their state.