Starhold Status

Webhooks

Each webhook endpoint has a secret URL. Point your monitoring tool at it and the component's state follows. Create endpoints in the dashboard, on the page's webhook section; the URL is shown once.

https://stage-status.starhold.app/in/YOUR_ENDPOINT_TOKEN

Uptime Kuma

  1. In the dashboard, add a webhook endpoint with source "Uptime Kuma" and pick the component.
  2. In Uptime Kuma, open Settings, Notifications, Setup Notification. Choose type "Webhook".
  3. Post URL: your endpoint URL above. Request body: "application/json" (the preset). Save, then attach the notification to your monitor.

Mapping: heartbeat status 1 (up) is operational, 0 (down) is major outage, 3 (maintenance) is maintenance. Status 2 (pending) is ignored.

Better Stack

  1. Add an endpoint with source "Better Stack" and pick the component.
  2. In Better Stack Uptime, open Integrations and add a Webhook. Use your endpoint URL and POST, and turn on incident started and incident resolved.

Mapping: incident started is major outage, resolved is operational, acknowledged is ignored.

Grafana

  1. Add an endpoint with source "Grafana", pick the component, and choose what a firing alert reports (major outage by default, or degraded).
  2. In Grafana, open Alerting, Contact points, add a contact point of type "Webhook". URL: your endpoint URL. HTTP method: POST. Route your alert rule to it.

Mapping: "status": "firing" becomes the state you chose, "status": "resolved" is operational.

Generic JSON

Anything that can send a POST works. Add an endpoint with source "Generic". On an endpoint bound to one component, send just the state:

curl -X POST https://stage-status.starhold.app/in/YOUR_ENDPOINT_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"state": "degraded"}'

On an endpoint that is not bound, name the component by its id or its exact name:

{"component": "API", "state": "major_outage"}

State is one of operational, degraded, partial_outage, major_outage, maintenance.

Outbound webhooks

Add a URL in the dashboard, on the page's "Outbound webhooks" section, and every incident and maintenance update on that page is sent to it. The URL must be https on a public address; the signing secret is shown once.

POST your-url
Content-Type: application/json
X-Starhold-Event: incident.update
X-Starhold-Delivery: 42
X-Starhold-Timestamp: 1790000000
X-Starhold-Signature: sha256=HEX

{"body_md":"...","event":"incident.update","page":{"title":"...","url":"..."},"sent_at":"...","status":"investigating","title":"..."}