Skip to content

Heartbeat Destination Shape

URI: https://docs.ankatech.co/errors/alert-heartbeat-destination-shape
HTTP Status: 422 Unprocessable Entity

When you see this

You declared or replaced a platform alert destination whose purpose is HEARTBEAT, and its shape contradicts that purpose. A heartbeat is a signed ping to a webhook on its own cadence, watched by an external dead-man's switch; it is not an alert subscription. The platform refuses every shape that would make it something else with this one problem type, so a client can say "a heartbeat is a webhook ping" without parsing a sentence.

It is distinct from the 400 a malformed field receives — a missing or out-of-range heartbeatIntervalSeconds is a 400 — and from the 422 Endpoint Not Permitted, which refuses the webhook address itself.

Common Causes

  • The HEARTBEAT destination uses a channel other than WEBHOOK (EMAIL, SMS or WHATSAPP). A heartbeat has no human reader; its absence is the signal, and only an external check can notice an absence.
  • The HEARTBEAT destination carries acceptedSeverities. A heartbeat receives no alerts, so a severity set is never read.
  • The HEARTBEAT destination carries quietHours. A dead-man's switch that goes quiet on schedule reports an outage every night.
  • An existing ALERT destination was replaced with purpose: HEARTBEAT while keeping its channel, severities or quiet hours.

Response Example

{
  "type": "https://docs.ankatech.co/errors/alert-heartbeat-destination-shape",
  "title": "Heartbeat Destination Shape",
  "status": 422,
  "detail": "A HEARTBEAT destination must use the WEBHOOK channel; EMAIL was requested.",
  "instance": "/api/v3/admin/platform/alerts/destinations",
  "extensions": {
    "requestId": "7c2e9a41-5b3d-4f08-8e61-2a9d4c7b3f15"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The detail names the rule and the channel only, never the webhook URL, which on the receivers a heartbeat targets is a bearer credential.

How to Resolve

  1. Declare the heartbeat as channel: WEBHOOK with a WEBHOOK config pointing at an external check (healthchecks.io, Better Stack, Cronitor or similar), and heartbeatIntervalSeconds between 60 and 3600.
  2. Omit acceptedSeverities and quietHours from a HEARTBEAT destination.
  3. To be alerted by email, SMS or WhatsApp, declare a separate ALERT destination on that channel; the external check, not the heartbeat, is what pages a person when the pings stop.