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_keystringAlert grouping hint, max 200 chars. Folded into the ping's metadata and read at event-generation time.
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 — always "Ping received". Use monitor.monitoringActive to tell whether this ping started or resumed monitoring.
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.