Uptime-Monitoring-API
Alles, was du in der App tust, geht auch über die REST-API: Monitore aus deiner Deployment-Pipeline anlegen, Verfügbarkeit und Antwortzeiten in eigene Dashboards holen, Status-Pages und Alarmkanäle synchron halten. JSON rein, JSON raus, ein Bearer-Token. API-Tokens gibt es ab dem Business-Tarif.
Erste Schritte
Basis-URL
https://app.centoculus.com/api/v1
Jede Anfrage trägt zwei Header: Authorization: Bearer <token> und Accept: application/json. Anfragen mit Body senden JSON mit Content-Type: application/json.
- Lege unter Mein Konto → API-Tokens in der Web-App oder der Handy-App ein Token an und wähle seine Scopes.
- Kopiere das Token sofort; es wird nur ein einziges Mal angezeigt.
- Rufe
GET /meauf. Das funktioniert mit jedem Token und zeigt dir, zu wem das Token gehört.
Dein erster Aufruf:
curl https://app.centoculus.com/api/v1/me \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json"
Die Antwort ist dein Benutzer mit Rolle, Sprache und den Arbeitsbereichen, die das Token erreicht (gekürzt):
{
"data": {
"id": 4821,
"name": "Mara Lindqvist",
"email": "mara@example.com",
"role": "customer_admin",
"role_label": "admin",
"locale": "en",
"timezone": "Europe/Stockholm",
"customers": [{"id": 1207, "name": "Example Ltd"}],
"default_customer_id": 1207
}
}
Tokens und Scopes
Ein Token hat einen Namen, ein optionales Ablaufdatum (bis zu 730 Tage) und die Scopes, die es nutzen darf. Vergib nur die Scopes, die eine Integration braucht: Ein Dashboard bekommt monitors:read und incidents:read, ein Deployment-Skript monitors:write. In Tarifen unter Business ist der Bereich sichtbar, aber ausgegraut.
| Scope | Erlaubt |
|---|---|
monitors:read | Monitore, Verfügbarkeit, Tagesverfügbarkeit, Antwortzeiten, Check-Typen, Standorte und Dashboard-Übersicht auflisten und anzeigen |
monitors:write | Monitore anlegen, ändern, löschen, pausieren und fortsetzen |
servers:read | Server und ihre Metriken auflisten und anzeigen |
servers:write | Server anlegen, ändern, löschen, pausieren und fortsetzen; neuer Installationsbefehl für den Agent |
incidents:read | Störungen und Dashboard-Übersicht auflisten und anzeigen |
status-pages:read | Status-Pages auflisten und anzeigen |
status-pages:write | Status-Pages und ihre Hinweise anlegen, ändern und löschen |
notifications:read | Benachrichtigungskanäle und Kanaltypen auflisten und anzeigen |
notifications:write | Kanäle (E-Mail, Telegram, Webhook, Push) anlegen, ändern und löschen, Test senden |
GET /me funktioniert mit jedem Token. Abrechnung, Team, Tokens, Kontosicherheit und Reparaturen sind mit einem API-Token nicht erreichbar und antworten mit 403, ebenso ein Aufruf ohne den passenden Scope.
Widerrufe ein Token an derselben Stelle; es funktioniert sofort nicht mehr.
Konventionen
- Antworten sind JSON. Ein einzelnes Objekt kommt unter
data, eine Liste unterdatamitlinksundmeta. - Monitore und Server werden über eine UUID angesprochen; Störungen, Status-Pages und Benachrichtigungskanäle über eine numerische ID.
- Zeiten sind ISO 8601 in UTC, zum Beispiel
2026-11-15T08:30:00.000000Z. - Listen sind mit den Query-Parametern
pageundper_pagepaginiert;metaenthältcurrent_page,last_page,per_pageundtotal. Standard-Seitengrößen: Monitore 15 (max. 200), Störungen 25 (max. 100), Benachrichtigungskanäle 50, Server 100, Status-Pages 15. - Konten mit mehreren Arbeitsbereichen (Partner und Reseller) übergeben beim Anlegen
customer_idund können Listen damit filtern. Kundenkonten lassen es weg. - Es gibt kein allgemeines Anfragekontingent. Einige Endpunkte sind gedrosselt, zum Beispiel das erneute Senden einer E-Mail-Bestätigung (10 pro Minute); sie antworten mit 429 und
Retry-After. Frage nicht öfter ab als dein Check-Intervall; für Live-Daten nimm einen Webhook-Kanal.
Fehler
Fehler sind JSON mit einer message. Validierungsfehler enthalten zusätzlich errors mit einer Liste von Meldungen pro Feld.
| Status | Bedeutung |
|---|---|
401 | Token fehlt, ist ungültig, abgelaufen oder widerrufen. |
402 | Das Monitoring ist pausiert, weil das Prepaid-Guthaben aufgebraucht ist (Reseller-Kunden); nach dem Aufladen läuft es weiter. |
403 | Dem Token fehlt der Scope, der Endpunkt ist für API-Tokens gesperrt oder dein Tarif enthält die Funktion nicht. |
404 | Nicht gefunden oder nicht in deinem Arbeitsbereich. |
409 | Konflikt, zum Beispiel wenn eine E-Mail-Adresse bestätigt werden soll, die schon bestätigt ist. |
422 | Validierung fehlgeschlagen; siehe errors. Bei einer erreichten Tarifgrenze nennt upgrade die Funktion, die ein größerer Tarif freischaltet. |
429 | Zu viele Anfragen an einen gedrosselten Endpunkt; warte die in Retry-After genannten Sekunden ab. |
Ein Validierungsfehler:
HTTP/1.1 422 Unprocessable Content
{
"message": "The target field is required. (and 1 more error)",
"errors": {
"target": ["The target field is required."],
"interval_seconds": ["The interval must be at least 60 seconds on your plan."]
}
}
Monitore
Ein Monitor ist ein Check: eine Website, ein SSL-Zertifikat, ein Ping, ein TCP-Port, ein DNS-Eintrag, ein Cron-Heartbeat oder das Mail-Setup einer Domain. Typen: http, ssl, ping, tcp, dns, heartbeat, maildns, mailflow. GET /check-types zeigt dir, welche Typen, Intervalle und Standorte dein Tarif enthält und welche Standardwerte jeder Typ hat.
| Endpunkt | Was er tut |
|---|---|
GET /monitors |
Auflisten; Filter status, search, ids (kommagetrennt), with_stats=1 ergänzt Verfügbarkeit und letzte Antwortzeit |
POST /monitors |
Anlegen; die Checks starten im Hintergrund |
GET /monitors/{id} |
Ein Monitor mit seinen Standorten und der offenen Störung |
PATCH /monitors/{id} |
Ändern; der Typ lässt sich nicht ändern |
DELETE /monitors/{id} |
Löschen (204) |
POST /monitors/{id}/pause |
Pausieren; eine offene Störung wird geschlossen |
POST /monitors/{id}/resume |
Fortsetzen |
GET /check-types |
Typen, Standardwerte und die Grenzen deines Tarifs |
GET /locations |
Aktive Check-Standorte (code, name, country) |
Felder beim Anlegen
| Feld | Beschreibung |
|---|---|
name |
Anzeigename, bis zu 255 Zeichen. Pflicht. |
type |
Einer der oben genannten Typen. Pflicht, danach unveränderlich. |
target |
URL, Hostname, IP-Adresse oder Domain, je nach Typ. Pflicht außer bei heartbeat, der dir stattdessen eine Ping-URL liefert. |
interval_seconds |
Check-Intervall. Das Minimum hängt von deinem Tarif ab; GET /check-types liefert es als limits.min_interval_seconds. |
locations |
Standortcodes, zum Beispiel ["eu", "sg"]. Wie viele du wählen darfst, hängt von deinem Tarif ab. |
primary_location |
Hauptstandort, der einen Ausfall zuerst bestätigt (Smart Verify). |
confirm_locations |
Wie viele Standorte den Fehler sehen müssen, bevor du alarmiert wirst (1–3). In größeren Tarifen einstellbar. |
confirm_checks |
Wie viele fehlgeschlagene Checks in Folge einen Ausfall bestätigen (1–3). In größeren Tarifen einstellbar. |
options |
Je nach Typ. Für http: method (GET, HEAD, POST), expected_status (z. B. 200-399 oder 200,301), keyword mit keyword_mode (present oder absent), timeout_seconds, check_ssl, warn_days, crit_days, allow_self_signed. Weggelassene Optionen übernehmen die Standardwerte aus GET /check-types. |
Einen Website-Check mit Schlüsselwort anlegen:
curl -X POST https://app.centoculus.com/api/v1/monitors \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "Shop",
"type": "http",
"target": "https://shop.example.com",
"interval_seconds": 60,
"locations": ["eu", "sg"],
"options": {"keyword": "Add to cart", "expected_status": "200-399"}
}'
Die Antwort (201) ist der Monitor. provisioning.state wechselt auf synced, sobald die Standorte ihn übernommen haben, status nach dem ersten Check von pending auf up:
{
"data": {
"id": "6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44",
"customer_id": 1207,
"name": "Shop",
"type": "http",
"target": "https://shop.example.com",
"interval_seconds": 60,
"options": {
"method": "GET",
"expected_status": "200-399",
"keyword": "Add to cart",
"keyword_mode": "present",
"timeout_seconds": 10,
"check_ssl": true,
"warn_days": 14,
"crit_days": 3,
"allow_self_signed": false
},
"location_codes": ["eu", "sg"],
"primary_location": "eu",
"smart_verify": true,
"confirm_locations": 1,
"confirm_checks": 1,
"status": "pending",
"is_paused": false,
"provisioning": {"state": "pending"},
"locations": [
{"code": "eu", "role": "primary", "name": "Europe", "status": "pending", "last_response_ms": null, "last_checked_at": null},
{"code": "sg", "role": "verify", "name": "Singapore", "status": "pending", "last_response_ms": null, "last_checked_at": null}
],
"open_incident": null,
"last_checked_at": null,
"status_changed_at": null,
"created_at": "2026-11-15T08:30:12.000000Z",
"updated_at": "2026-11-15T08:30:12.000000Z"
}
}
Statuswerte: pending, up, degraded, down, paused.
Einen Monitor während eines Deployments pausieren und danach fortsetzen:
curl -X POST https://app.centoculus.com/api/v1/monitors/6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44/pause \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
curl -X POST https://app.centoculus.com/api/v1/monitors/6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44/resume \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
Verfügbarkeit und Antwortzeiten
Die Verfügbarkeit wird aus Ausfällen berechnet (Störungen mit Schweregrad major); Warnungen wie ein ablaufendes Zertifikat zählen nicht. Noch nicht geprüft heißt null, nicht 100.
| Endpunkt | Was er tut |
|---|---|
GET /monitors/{id}/uptime |
Verfügbarkeit in Prozent für die letzten 24 Stunden, 7 Tage und 30 Tage |
GET /monitors/{id}/daily-uptime |
Verfügbarkeit pro Kalendertag (UTC), days 1–90, Standard 30 |
GET /monitors/{id}/response-times |
Antwortzeit und Verfügbarkeit pro Standort, range 24h, 7d oder 30d; stündliche Punkte, bei 30d täglich |
Verfügbarkeit:
curl https://app.centoculus.com/api/v1/monitors/6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44/uptime \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
{"data": {"24h": 100, "7d": 99.952, "30d": 99.987}}
Antwortzeiten (gekürzt):
curl "https://app.centoculus.com/api/v1/monitors/6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44/response-times?range=24h" \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
{
"data": {
"range": "24h",
"locations": {
"eu": [
{"time": "2026-11-15T07:00:00+00:00", "avg_ms": 212.4, "min_ms": 180, "max_ms": 402, "availability": 100},
{"time": "2026-11-15T08:00:00+00:00", "avg_ms": 230.1, "min_ms": 190, "max_ms": 388, "availability": 100}
],
"sg": [
{"time": "2026-11-15T07:00:00+00:00", "avg_ms": 512.8, "min_ms": 470, "max_ms": 790, "availability": 100}
]
}
}
}
Server
Ein Server ist eine Maschine mit dem Agent, der CPU, Arbeitsspeicher, Last, Festplatten, Netzwerk und Dienste meldet. Beim Anlegen eines Servers bekommst du den einmaligen Installationsbefehl; führe ihn auf der Maschine aus, und der Server erscheint einen Moment später.
| Endpunkt | Was er tut |
|---|---|
GET /servers |
Auflisten; Filter ids |
POST /servers |
Anlegen; die Antwort enthält install_command (Linux) und install_command_freebsd |
GET /servers/{id} |
Ein Server mit Inventar, letztem Snapshot und Schwellenwerten |
PATCH /servers/{id} |
Umbenennen, überwachte services wählen, thresholds setzen |
DELETE /servers/{id} |
Löschen (204); der Agent wird aus dem Monitoring entfernt |
POST /servers/{id}/pause |
Pausieren; offene Störungen werden geschlossen |
POST /servers/{id}/resume |
Fortsetzen |
POST /servers/{id}/install-token |
Neuer Installationsbefehl; rotate_key=true stellt zusätzlich einen neuen Agent-Schlüssel aus |
GET /servers/{id}/metrics |
Diagrammreihen, range 24h, 7d oder 30d: Metrik → Kontext → [unix time, avg, min, max] |
| Feld | Beschreibung |
|---|---|
name |
Anzeigename, bis zu 100 Zeichen. Pflicht beim Anlegen. |
services |
Dienstnamen, die der Agent überwachen soll, zum Beispiel ["nginx", "php8.4-fpm", "mariadb"]; bis zu 200. Der Server meldet, was er gefunden hat, unter discovered.services. |
thresholds |
Alarm-Schwellenwerte: cpu_max (Prozent), load_max_per_cpu, mem_min_pavail (Prozent frei), fs_warn und fs_crit (Prozent belegt), inode_warn, agent_nodata_minutes, pro Mountpunkt unter filesystems sowie die regulären Ausdrücke fs_types, fs_exclude, net_exclude. Weggelassene Werte behalten die Standardwerte. |
Einen Server hinzufügen und den Installationsbefehl aus der Antwort lesen:
curl -X POST https://app.centoculus.com/api/v1/servers \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name": "web-1"}'
{
"data": {
"id": "a3b9d6e2-5f10-4b8c-9e77-2c4d1a0f6b58",
"customer_id": 1207,
"name": "web-1",
"status": "pending",
"is_paused": false,
"provisioning": {"state": "pending"},
"services": [],
"install_token_expires_at": "2026-11-16T08:30:12.000000Z",
"install_command": "curl -fsSL https://app.centoculus.com/install/K7xQ2mVt9…Rd | sudo sh",
"install_command_freebsd": "fetch -qo - https://app.centoculus.com/install/K7xQ2mVt9…Rd | sh",
"created_at": "2026-11-15T08:30:12.000000Z"
}
}
Drei Dienste überwachen und bei 80 Prozent Festplattenbelegung alarmieren:
curl -X PATCH https://app.centoculus.com/api/v1/servers/a3b9d6e2-5f10-4b8c-9e77-2c4d1a0f6b58 \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"services": ["nginx", "php8.4-fpm", "mariadb"],
"thresholds": {"fs_warn": 80, "fs_crit": 90}
}'
Störungen
Eine Störung ist ein Ausfall oder eine Warnung eines Monitors oder Servers, von started_at bis resolved_at. Jede Störung trägt ihre Alarmnummer, dieselbe, die die Alarm-E-Mail zeigt.
| Endpunkt | Was er tut |
|---|---|
GET /incidents |
Neueste zuerst; Filter monitor_id, status (open oder closed), open=1 (offene Ausfälle ohne Hinweise), from und to (Datumsangaben) |
GET /incidents/{id} |
Eine Störung mit ihrem Verlauf: wann welcher Standort ausgefallen und wieder erreichbar war, und die Reparatur, die sie behoben hat |
Offene Störungen:
curl "https://app.centoculus.com/api/v1/incidents?status=open&per_page=10" \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
{
"data": [
{
"id": 90412,
"monitor_id": "6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44",
"monitor_name": "Shop",
"server_id": null,
"subject_type": "monitor",
"severity": "major",
"cause": "unreachable",
"started_at": "2026-11-15T09:14:03.000000Z",
"resolved_at": null,
"duration_seconds": 241,
"alert_number": 101,
"alert_label": "Incident #101",
"affected_locations": ["eu", "sg"],
"failure_reason": "HTTP 502 instead of 200-399",
"fix": null
}
],
"links": {"first": "…?page=1", "last": "…?page=1", "prev": null, "next": null},
"meta": {"current_page": 1, "from": 1, "last_page": 1, "per_page": 10, "to": 1, "total": 1}
}
Nützliche Felder: subject_type (monitor oder server), severity (major, warning, info), cause (zum Beispiel unreachable, network_issue, certificate_expiring, heartbeat_missed), duration_seconds, affected_locations und, solange die Störung offen ist, failure_reason mit den letzten Check-Werten.
Status-Pages
Eine Status-Page zeigt ausgewählte Monitore öffentlich oder deinem Team, unter unserer Domain oder deiner eigenen. Hinweise kündigen Wartungen an oder erklären eine laufende Störung.
| Endpunkt | Was er tut |
|---|---|
GET /status-pages |
Auflisten |
POST /status-pages |
Anlegen |
GET /status-pages/{id} |
Eine Seite mit Monitoren, Hinweisen und dem Zustand ihrer Domains |
PATCH /status-pages/{id} |
Ändern; monitors ersetzt die ganze Liste |
DELETE /status-pages/{id} |
Löschen (204) |
POST /status-pages/{id}/notices |
Hinweis hinzufügen |
PUT /status-pages/{id}/notices/{notice} |
Hinweis ändern |
DELETE /status-pages/{id}/notices/{notice} |
Hinweis entfernen (204) |
| Feld | Beschreibung |
|---|---|
slug |
Adressteil, 3–63 Zeichen, Kleinbuchstaben, Ziffern und Bindestriche; eindeutig. Pflicht. |
title |
Überschrift der Seite. Pflicht. |
description |
Kurzer Text unter der Überschrift, bis zu 2000 Zeichen. |
logo_url |
HTTPS-Adresse eines Logos. |
custom_domain |
Eigene Domain wie status.example.com; erfordert einen Tarif mit eigenen Status-Domains. |
is_public |
Öffentlich (true) oder nur für angemeldete Benutzer. |
monitors |
Geordnete Liste von {"id": "<monitor UUID>", "display_name": "…", "group": "…"}; display_name und group sind optional. |
Ein Hinweis hat kind (maintenance, info oder incident), title, body (optional, bis zu 5000 Zeichen), starts_at und ein optionales ends_at.
Eine öffentliche Status-Page mit zwei Monitoren anlegen:
curl -X POST https://app.centoculus.com/api/v1/status-pages \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"slug": "example-status",
"title": "Example status",
"is_public": true,
"monitors": [
{"id": "6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44", "display_name": "Online shop", "group": "Web"},
{"id": "9c2d4e6f-1a3b-4c5d-8e7f-6a5b4c3d2e1f", "group": "Web"}
]
}'
Ein Wartungsfenster ankündigen:
curl -X POST https://app.centoculus.com/api/v1/status-pages/318/notices \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"kind": "maintenance",
"title": "Database upgrade",
"body": "Checkout will be unavailable for about 15 minutes.",
"starts_at": "2026-11-20T01:00:00Z",
"ends_at": "2026-11-20T01:30:00Z"
}'
Benachrichtigungskanäle
Ein Benachrichtigungskanal ist ein Weg, jemanden zu erreichen: eine E-Mail-Adresse, ein Telegram-Chat, ein Webhook oder die Push-Geräte eines Benutzers. Ein Kanal erhält die Alarme aller Monitore des Arbeitsbereichs oder nur die der Monitore in monitor_ids. Welche Kanaltypen dein Tarif enthält: GET /notification-channel-types.
| Endpunkt | Was er tut |
|---|---|
GET /notification-channels |
Auflisten |
POST /notification-channels |
Anlegen; bei einem Webhook steht das Signatur-secret nur in dieser Antwort |
GET /notification-channels/{id} |
Ein Kanal |
PATCH /notification-channels/{id} |
Ändern; der Typ lässt sich nicht ändern |
DELETE /notification-channels/{id} |
Löschen (204) |
POST /notification-channels/{id}/test |
Testbenachrichtigung senden (202); eine unbestätigte E-Mail-Adresse bekommt stattdessen ihren Bestätigungslink erneut |
GET /notification-channel-types |
Kanaltypen mit available und paid |
| Feld | Beschreibung |
|---|---|
type |
email, telegram, webhook oder push. Pflicht, danach unveränderlich. |
name |
Anzeigename. Pflicht. |
config |
Je nach Typ: {"email": "…"}, {"chat_id": "…"} oder {"url": "https://…"}. Push braucht keine Konfiguration. Eine neue E-Mail-Adresse muss per Link bestätigt werden, bevor Alarme verschickt werden. |
monitor_ids |
UUIDs der Monitore, für die dieser Kanal gilt; lass das Feld weg für alle Monitore. |
quiet_hours |
{"start": "22:00", "end": "07:00", "timezone": "Europe/Berlin"}: keine Alarme in diesem Zeitfenster. |
escalation_delay_minutes |
Diesen Kanal nur alarmieren, wenn ein Ausfall so lange dauert (0–1440). |
notify_recovery |
Auch die Entwarnung senden (true oder false). |
is_active |
Den Kanal ein- oder ausschalten, ohne ihn zu löschen. |
Einen Webhook-Kanal für zwei Monitore anlegen und das Secret aufbewahren:
curl -X POST https://app.centoculus.com/api/v1/notification-channels \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"type": "webhook",
"name": "Ops bot",
"config": {"url": "https://hooks.example.com/centoculus"},
"monitor_ids": ["6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44", "9c2d4e6f-1a3b-4c5d-8e7f-6a5b4c3d2e1f"],
"notify_recovery": true
}'
{
"data": {
"id": 512,
"customer_id": 1207,
"type": "webhook",
"name": "Ops bot",
"config": {"url": "https://hooks.example.com/centoculus", "secret": "wq7Hc2…48 characters…Zp"},
"quiet_hours": null,
"escalation_delay_minutes": 0,
"notify_recovery": true,
"is_active": true,
"confirmed": true,
"monitor_ids": ["6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44", "9c2d4e6f-1a3b-4c5d-8e7f-6a5b4c3d2e1f"],
"created_at": "2026-11-15T08:41:55.000000Z",
"updated_at": "2026-11-15T08:41:55.000000Z"
}
}
Webhook-Payload
Ein Webhook-Kanal sendet jeden Alarm per POST als JSON an deine URL, mit 10 Sekunden Timeout und ohne Weiterleitungen. Das Ziel muss eine öffentliche Adresse sein.
Header: X-Webhook-Timestamp (Unix-Zeit), X-Webhook-Signature (sha256= gefolgt vom HMAC-SHA256 von <timestamp>.<body> mit dem Kanal-Secret als Schlüssel) und User-Agent: Uptime-Webhook/1.
event ist down, recovered, paused oder test. Bei einem Monitor-Alarm enthält der Body monitor (id, name, target) und incident (id, severity, cause, started_at, resolved_at, duration_seconds, affected_locations); bei einem Server-Alarm server (id, name) und incident mit problem statt der Standorte. subject ist die Überschrift des Alarms in der Sprache des Kanals.
Body eines Down-Alarms:
POST /your-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Uptime-Webhook/1
X-Webhook-Timestamp: 1794912843
X-Webhook-Signature: sha256=3f1b9c…e2a7
{
"event": "down",
"monitor": {"id": "6f1c2b1e-9d3a-4c7e-8b21-0f5a1d2e3c44", "name": "Shop", "target": "https://shop.example.com"},
"incident": {
"id": 90412,
"severity": "major",
"cause": "unreachable",
"started_at": "2026-11-15T09:14:03+00:00",
"resolved_at": null,
"duration_seconds": 0,
"affected_locations": ["eu", "sg"]
},
"subject": "DOWN: Shop"
}
Prüfe die Signatur, bevor du dem Body vertraust: Berechne den HMAC über den Roh-Body genau so, wie er ankommt, und vergleiche in konstanter Zeit. Weise Zeitstempel zurück, die älter als ein paar Minuten sind.
Die Signatur in einer Shell prüfen:
expected="sha256=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')"
[ "$expected" = "$SIGNATURE" ] && echo "valid"
Dashboard-Übersicht
GET /dashboard liefert die Zahlen hinter den Kacheln der Übersicht: Monitore pro Status (Server zählen mit ihren Tarifeinheiten), Server pro Status und die Anzahl offener Störungen. Jeder der Scopes monitors:read, servers:read oder incidents:read öffnet ihn.
curl https://app.centoculus.com/api/v1/dashboard \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" -H "Accept: application/json"
{
"data": {
"monitors": {"pending": 0, "up": 46, "degraded": 1, "down": 1, "paused": 2},
"monitors_total": 50,
"servers": {"pending": 0, "up": 3, "degraded": 0, "down": 0, "paused": 0},
"open_incidents": 2
}
}
Häufige Fragen
Welcher Tarif enthält die API?
API-Tokens gibt es ab dem Business-Tarif. In kleineren Tarifen siehst du den Bereich unter Mein Konto ausgegraut mit einem Upgrade-Link. Alles andere in Centoculus funktioniert ohne die API.
Kann ein Token alles, was mein Konto kann?
Nein. Ein Token erreicht nur die Bereiche, für die du ihm Scopes gegeben hast, und nie Abrechnung, Teammitglieder, andere Tokens, Kontosicherheit oder Reparaturen. Die bleiben in der App.
Gibt es eine Sandbox?
Nutze zum Ausprobieren ein Token nur mit Lese-Scopes und lege Test-Monitore im kostenlosen Tarif eines zweiten Kontos an. Monitore, die du anlegst, zählen wie die in der App erstellten auf deinen Tarif.
Wie bekomme ich Alarme in mein eigenes System?
Lege einen Webhook-Kanal an und prüfe bei jeder Zustellung die Signatur. Jeder Ausfall, jede Wiederherstellung und jede Pause erreicht deine URL innerhalb von Sekunden, mit Monitor, Ursache und betroffenen Standorten als JSON.
Ändert sich die API?
Die Version steht in der Adresse (/api/v1). Neue Felder können jederzeit zu Antworten hinzukommen; innerhalb einer Version werden Felder weder entfernt noch umbenannt. Lies, was du brauchst, und ignoriere den Rest.
Bereit, dein Monitoring zu automatisieren?
API-Tokens sind ab dem Business-Tarif enthalten. Vergleiche die Tarife oder starte kostenlos und wechsle, sobald deine Skripte fertig sind.