Heartbeat ping

The endpoint that monitors expect your service to call on a cadence.

POST/api/ping/{pingUrl}

{pingUrl} is the monitor's unique identifier — find it on the monitor detail page. Both POST and GET are accepted; POST with a JSON body is the recommended form.

Headers

FieldTypeDescription
X-Webhook-SignaturerequiredstringHMAC-SHA256 of the request body hex-encoded with the team webhook secret. See Authentication.
Content-Typeapplication/jsonRequired when sending a JSON body.

Body

The body is optional. When omitted, the ping is treated as status: "up".

FieldTypeDescription
status"up" | "down"Defaults to "up". Sending "down" raises an incident immediately.
reasonstringOptional reason string, max 200 chars. Persists on the ping row and drives down→down dedup.
group_keystringRouting hint used at alert-firing time, max 200 chars. Not persisted.
metadataobjectArbitrary key-value payload. If you POST extra top-level fields, they are folded into metadata automatically.

Example request

BODY='{"status":"up","metadata":{"batch":1247,"durationMs":832}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$OPSHIFT_SECRET" -hex | awk '{print $2}')
 
curl -X POST https://www.opshift.io/api/ping/payments-worker \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIG" \
  -d "$BODY"

Response

Returns 200 OK on success.

json
{
  "message": "Ping received",
  "monitor": {
    "name": "Payments worker",
    "status": "up",
    "monitoringActive": true
  },
  "pingStatus": "up"
}

Response fields

FieldTypeDescription
messagestringHuman-readable summary. First-ever ping returns "First ping received — monitoring started"; first ping after a resume returns "Ping received — monitoring restarted".
monitor.namestringThe monitor's display name.
monitor.status"idle" | "up" | "down" | "paused"Effective monitor status after this ping.
monitor.monitoringActivebooleanTrue once monitoring has started (first ping ever or first ping after resume).
pingStatus"up" | "down"The status that this ping reported.

Errors

FieldTypeDescription
401UnauthorizedMissing or invalid signature.
403ForbiddenTeam subscription expired.
404Not foundUnknown ping URL, or the monitor is paused.
429Too many requestsRate limit exceeded (max 10 pings per minute per ping URL) or monthly heartbeat quota exhausted.