Siirry sisältöön
Centoculus

Käyttökatkojen valvonnan API

Kaiken, minkä teet sovelluksessa, voit tehdä myös REST API:n kautta: luo valvontoja julkaisuputkestasi, tuo käytettävyys ja vasteajat omiin kojelautoihisi, pidä tilasivut ja hälytyskanavat synkronoituina. JSON sisään, JSON ulos, yksi Bearer-token. API-tokenit kuuluvat Business-paketista alkaen.

Aloittaminen

Perusosoite

https://app.centoculus.com/api/v1

Jokaisessa pyynnössä on kaksi otsaketta: Authorization: Bearer <token> ja Accept: application/json. Sisältöä sisältävät pyynnöt lähettävät JSONia otsakkeella Content-Type: application/json.

  1. Luo token kohdassa Oma tili → API-tokenit verkkosovelluksessa tai mobiilisovelluksessa ja valitse sen oikeudet (scopet).
  2. Kopioi token heti; se näytetään vain kerran.
  3. Kutsu GET /me. Se toimii jokaisella tokenilla ja kertoo, kenen token on.

Ensimmäinen kutsusi:

curl https://app.centoculus.com/api/v1/me \
  -H "Authorization: Bearer $CENTOCULUS_TOKEN" \
  -H "Accept: application/json"

Vastauksena on käyttäjäsi rooleineen, kielineen ja työtiloineen, joihin token yltää (lyhennetty):

{
  "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
  }
}

Tokenit ja oikeudet

Tokenilla on nimi, valinnainen vanhenemisaika (enintään 730 päivää) ja oikeudet, joita se saa käyttää. Valitse vain ne oikeudet, joita integraatio tarvitsee: kojelauta saa monitors:read ja incidents:read, julkaisuskripti saa monitors:write. Business-pakettia pienemmissä paketeissa osio näkyy, mutta on harmaana.

Oikeus (scope)Sallii
monitors:readValvontojen listaus ja katselu, käytettävyys, päivittäinen käytettävyys, vasteajat, tarkistustyypit, sijainnit, kojelaudan yhteenveto
monitors:writeValvontojen luonti, muokkaus, poisto, keskeytys ja jatkaminen
servers:readPalvelimien ja niiden mittausten listaus ja katselu
servers:writePalvelimien luonti, muokkaus, poisto, keskeytys ja jatkaminen; uusi asennuskomento agentille
incidents:readHäiriöiden listaus ja katselu, kojelaudan yhteenveto
status-pages:readTilasivujen listaus ja katselu
status-pages:writeTilasivujen ja niiden tiedotteiden luonti, muokkaus ja poisto
notifications:readIlmoituskanavien ja kanavatyyppien listaus ja katselu
notifications:writeKanavien (sähköposti, Telegram, webhook, push) luonti, muokkaus ja poisto, testin lähetys

GET /me toimii jokaisella tokenilla. Laskutus, tiimi, tokenit, tilin tietoturva ja korjaukset (fixes) eivät ole API-tokenilla tavoitettavissa ja palauttavat 403, samoin kutsu ilman vastaavaa oikeutta.

Peruuta token samasta paikasta; se lakkaa toimimasta heti.

Käytännöt

  • Vastaukset ovat JSONia. Yksittäinen objekti on kentässä data, lista kentässä data yhdessä links- ja meta-kenttien kanssa.
  • Valvonnat ja palvelimet osoitetaan UUID:llä; häiriöt, tilasivut ja ilmoituskanavat numeerisella id:llä.
  • Ajat ovat ISO 8601 -muodossa UTC-aikana, esimerkiksi 2026-11-15T08:30:00.000000Z.
  • Listat sivutetaan kyselyparametreilla page ja per_page; meta sisältää kentät current_page, last_page, per_page ja total. Oletussivukoot: valvonnat 15 (enintään 200), häiriöt 25 (enintään 100), ilmoituskanavat 50, palvelimet 100, tilasivut 15.
  • Tilit, joilla on useita työtiloja (kumppanit ja jälleenmyyjät), antavat luodessaan customer_id:n ja voivat suodattaa sillä listoja. Asiakastilit jättävät sen pois.
  • Yleistä pyyntökiintiötä ei ole. Muutamia päätepisteitä rajoitetaan, esimerkiksi sähköpostivahvistuksen uudelleenlähetystä (10 minuutissa); ne vastaavat 429 ja Retry-After. Älä kysele useammin kuin tarkistusvälisi; reaaliaikaiseen dataan käytä webhook-kanavaa.

Virheet

Virheet ovat JSONia, jossa on message. Validointivirheissä on lisäksi errors, jossa on kentittäin lista viesteistä.

TilaMerkitys
401Token puuttuu tai on virheellinen, vanhentunut tai peruutettu.
402Valvonta on keskeytetty, koska ennakkoon maksettu saldo on käytetty loppuun (jälleenmyyjän asiakkaat); se jatkuu latauksen jälkeen.
403Tokenilta puuttuu oikeus, päätepiste on suljettu API-tokeneilta tai pakettisi ei sisällä ominaisuutta.
404Ei löydy tai ei ole työtilassasi.
409Ristiriita, esimerkiksi jo vahvistetun sähköpostiosoitteen vahvistaminen.
422Validointi epäonnistui; katso errors. Kun paketin raja tulee vastaan, upgrade kertoo ominaisuuden, jonka suurempi paketti avaa.
429Liikaa pyyntöjä rajoitettuun päätepisteeseen; odota Retry-After-kentän ilmoittama määrä sekunteja.

Validointivirhe:

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."]
  }
}

Valvonnat

Valvonta on yksi tarkistus: verkkosivu, SSL-varmenne, ping, TCP-portti, DNS-tietue, cron-heartbeat tai verkkotunnuksen sähköpostiasetukset. Tyypit: http, ssl, ping, tcp, dns, heartbeat, maildns, mailflow. GET /check-types kertoo, mitkä tyypit, välit ja sijainnit pakettisi sisältää, sekä jokaisen tyypin oletukset.

PäätepisteMitä se tekee
GET /monitors Lista; suodattimet status, search, ids (pilkulla erotettu), with_stats=1 lisää käytettävyyden ja viimeisimmän vasteajan
POST /monitors Luo; tarkistukset käynnistyvät taustalla
GET /monitors/{id} Yksi valvonta sijainteineen ja avoimine häiriöineen
PATCH /monitors/{id} Päivitä; tyyppiä ei voi vaihtaa
DELETE /monitors/{id} Poista (204)
POST /monitors/{id}/pause Keskeytä; avoin häiriö suljetaan
POST /monitors/{id}/resume Jatka
GET /check-types Tyypit, oletukset ja pakettisi rajat
GET /locations Aktiiviset tarkistussijainnit (code, name, country)

Kentät luotaessa

KenttäKuvaus
name Näyttönimi, enintään 255 merkkiä. Pakollinen.
type Jokin yllä olevista tyypeistä. Pakollinen, ei muutettavissa jälkeenpäin.
target URL, isäntänimi, IP-osoite tai verkkotunnus tyypistä riippuen. Pakollinen paitsi heartbeat-tyypille, joka antaa sinulle sen sijaan ping-URL:n.
interval_seconds Tarkistusväli. Vähimmäisväli riippuu paketistasi; GET /check-types palauttaa sen kenttänä limits.min_interval_seconds.
locations Sijaintikoodit, esimerkiksi ["eu", "sg"]. Kuinka monta voit valita, riippuu paketistasi.
primary_location Pääsijainti, joka vahvistaa katkot ensimmäisenä (Smart Verify).
confirm_locations Kuinka monen sijainnin on nähtävä vika, ennen kuin sinua hälytetään (1–3). Määritettävissä suuremmissa paketeissa.
confirm_checks Kuinka monta peräkkäistä epäonnistunutta tarkistusta vahvistaa katkon (1–3). Määritettävissä suuremmissa paketeissa.
options Tyyppikohtaisesti. Tyypille http: method (GET, HEAD, POST), expected_status (esim. 200-399 tai 200,301), keyword ja keyword_mode (present tai absent), timeout_seconds, check_ssl, warn_days, crit_days, allow_self_signed. Pois jätetyt asetukset saavat oletukset kutsusta GET /check-types.

Luo verkkosivun tarkistus avainsanalla:

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"}
  }'

Vastaus (201) on valvonta. provisioning.state muuttuu arvoon synced, kun sijainnit ovat ottaneet sen haltuunsa, ja status arvosta pending arvoon up ensimmäisen tarkistuksen jälkeen:

{
  "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"
  }
}

Tila-arvot: pending, up, degraded, down, paused.

Keskeytä valvonta julkaisun ajaksi ja jatka sitä sen jälkeen:

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"

Käytettävyys ja vasteajat

Käytettävyys lasketaan katkoista (häiriöt, joiden vakavuus on major); varoitukset, kuten vanheneva varmenne, eivät lasketa. Ei vielä tarkistettu tarkoittaa arvoa null, ei 100.

PäätepisteMitä se tekee
GET /monitors/{id}/uptime Käytettävyys prosentteina viimeiseltä 24 tunnilta, 7 päivältä ja 30 päivältä
GET /monitors/{id}/daily-uptime Käytettävyys kalenteripäivittäin (UTC), days 1–90, oletus 30
GET /monitors/{id}/response-times Vasteaika ja saatavuus sijainneittain, range 24h, 7d tai 30d; tuntipisteet, 30d:lle päiväpisteet

Käytettävyys:

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}}

Vasteajat (lyhennetty):

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}
      ]
    }
  }
}

Palvelimet

Palvelin on kone, johon on asennettu agentti, joka raportoi suorittimen, muistin, kuorman, levyt, verkon ja palvelut. Palvelimen luonti palauttaa kertakäyttöisen asennuskomennon; aja se koneella, niin palvelin ilmestyy hetken kuluttua.

PäätepisteMitä se tekee
GET /servers Lista; suodatin ids
POST /servers Luo; vastauksessa ovat install_command (Linux) ja install_command_freebsd
GET /servers/{id} Yksi palvelin laiteluetteloineen, viimeisimpine tilannekuvineen ja raja-arvoineen
PATCH /servers/{id} Nimeä uudelleen, valitse valvotut services, aseta thresholds
DELETE /servers/{id} Poista (204); agentti poistetaan valvonnasta
POST /servers/{id}/pause Keskeytä; avoimet häiriöt suljetaan
POST /servers/{id}/resume Jatka
POST /servers/{id}/install-token Uusi asennuskomento; rotate_key=true antaa myös uuden agenttiavaimen
GET /servers/{id}/metrics Kaaviosarjat, range 24h, 7d tai 30d: mittari → konteksti → [unix time, avg, min, max]
KenttäKuvaus
name Näyttönimi, enintään 100 merkkiä. Pakollinen luotaessa.
services Palvelunimet, joita agentin tulee valvoa, esimerkiksi ["nginx", "php8.4-fpm", "mariadb"]; enintään 200. Palvelin raportoi löytämänsä kohdassa discovered.services.
thresholds Hälytysrajat: cpu_max (prosenttia), load_max_per_cpu, mem_min_pavail (prosenttia vapaana), fs_warn ja fs_crit (prosenttia käytetty), inode_warn, agent_nodata_minutes, liitoskohtaisesti kohdassa filesystems sekä säännölliset lausekkeet fs_types, fs_exclude, net_exclude. Pois jätetyt arvot säilyttävät oletuksensa.

Lisää palvelin ja lue asennuskomento vastauksesta:

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"
  }
}

Valvo kolmea palvelua ja hälytä, kun levyn käyttö on 80 prosenttia:

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}
  }'

Häiriöt

Häiriö on valvonnan tai palvelimen yksi katko tai varoitus ajalta started_at – resolved_at. Jokaisella häiriöllä on hälytysnumero, sama kuin hälytyssähköpostissa.

PäätepisteMitä se tekee
GET /incidents Uusin ensin; suodattimet monitor_id, status (open tai closed), open=1 (avoimet katkot ilman tiedotteita), from ja to (päivämäärät)
GET /incidents/{id} Yksi häiriö aikajanoineen: milloin mikäkin sijainti kaatui ja palautui, sekä korjaus (fix), joka sen hoiti

Avoimet häiriöt:

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}
}

Hyödylliset kentät: subject_type (monitor tai server), severity (major, warning, info), cause (esimerkiksi unreachable, network_issue, certificate_expiring, heartbeat_missed), duration_seconds, affected_locations ja häiriön ollessa avoin failure_reason viimeisimpine tarkistusarvoineen.

Tilasivut

Tilasivu näyttää valitut valvonnat yleisölle tai tiimillesi, meidän verkkotunnuksessamme tai omassasi. Tiedotteet ilmoittavat huollosta tai selittävät käynnissä olevan häiriön.

PäätepisteMitä se tekee
GET /status-pages Lista
POST /status-pages Luo
GET /status-pages/{id} Yksi sivu valvontoineen, tiedotteineen ja verkkotunnustensa tiloineen
PATCH /status-pages/{id} Päivitä; monitors korvaa koko listan
DELETE /status-pages/{id} Poista (204)
POST /status-pages/{id}/notices Lisää tiedote
PUT /status-pages/{id}/notices/{notice} Päivitä tiedote
DELETE /status-pages/{id}/notices/{notice} Poista tiedote (204)
KenttäKuvaus
slug Osoitteen osa, 3–63 merkkiä, pieniä kirjaimia, numeroita ja yhdysmerkkejä; yksilöllinen. Pakollinen.
title Sivun otsikko. Pakollinen.
description Lyhyt teksti otsikon alla, enintään 2000 merkkiä.
logo_url Logon HTTPS-osoite.
custom_domain Oma verkkotunnus, kuten status.example.com; vaatii paketin, jossa on omat tilasivujen verkkotunnukset.
is_public Julkinen (true) tai vain kirjautuneille käyttäjille.
monitors Järjestetty lista muodossa {"id": "<monitor UUID>", "display_name": "…", "group": "…"}; display_name ja group ovat valinnaisia.

Tiedotteella on kind (maintenance, info tai incident), title, body (valinnainen, enintään 5000 merkkiä), starts_at ja valinnainen ends_at.

Luo julkinen tilasivu kahdella valvonnalla:

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"}
    ]
  }'

Ilmoita huoltoikkuna:

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"
  }'

Ilmoituskanavat

Ilmoituskanava on yksi tapa tavoittaa joku: sähköpostiosoite, Telegram-keskustelu, webhook tai käyttäjän push-laitteet. Kanava saa kaikkien työtilan valvontojen hälytykset tai vain monitor_ids-kentässä olevien valvontojen hälytykset. Mitkä kanavatyypit pakettisi sisältää, selviää kutsulla GET /notification-channel-types.

PäätepisteMitä se tekee
GET /notification-channels Lista
POST /notification-channels Luo; webhookin allekirjoitusavain secret on vain tässä vastauksessa
GET /notification-channels/{id} Yksi kanava
PATCH /notification-channels/{id} Päivitä; tyyppiä ei voi vaihtaa
DELETE /notification-channels/{id} Poista (204)
POST /notification-channels/{id}/test Lähetä testi-ilmoitus (202); vahvistamaton sähköpostiosoite saa sen sijaan vahvistuslinkkinsä uudelleen
GET /notification-channel-types Kanavatyypit kentin available ja paid
KenttäKuvaus
type email, telegram, webhook tai push. Pakollinen, ei muutettavissa jälkeenpäin.
name Näyttönimi. Pakollinen.
config Tyyppikohtaisesti: {"email": "…"}, {"chat_id": "…"} tai {"url": "https://…"}. Push ei tarvitse configia. Uusi sähköpostiosoite on vahvistettava linkillä, ennen kuin hälytyksiä lähtee.
monitor_ids Niiden valvontojen UUID:t, joita kanava koskee; jätä pois, jos kanava koskee kaikkia valvontoja.
quiet_hours {"start": "22:00", "end": "07:00", "timezone": "Europe/Berlin"}: ei hälytyksiä tänä aikana.
escalation_delay_minutes Hälytä tätä kanavaa vasta, kun katko on kestänyt näin kauan (0–1440).
notify_recovery Lähetä myös ilmoitus siitä, että kaikki on taas kunnossa (true tai false).
is_active Kytke kanava päälle tai pois poistamatta sitä.

Luo webhook-kanava kahdelle valvonnalle ja säilytä secret:

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"
  }
}

Webhookin sisältö

Webhook-kanava lähettää jokaisen hälytyksen JSONina POST-pyynnöllä URL-osoitteeseesi, 10 sekunnin aikakatkaisulla ja ilman uudelleenohjauksia. Kohteen on oltava julkinen osoite.

Otsakkeet: X-Webhook-Timestamp (Unix-aika), X-Webhook-Signature (sha256= ja sen perässä <timestamp>.<body>-merkkijonon HMAC-SHA256, avaimena kanavan secret) sekä User-Agent: Uptime-Webhook/1.

event on down, recovered, paused tai test. Valvonnan hälytyksessä body sisältää kentät monitor (id, name, target) ja incident (id, severity, cause, started_at, resolved_at, duration_seconds, affected_locations); palvelimen hälytyksessä server (id, name) ja incident, jossa on sijaintien sijaan problem. subject on hälytyksen otsikko kanavan kielellä.

Down-hälytyksen body:

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"
}

Varmista allekirjoitus, ennen kuin luotat sisältöön: laske HMAC raa'asta bodysta täsmälleen sellaisena kuin se vastaanotettiin ja vertaa vakioajassa. Hylkää aikaleimat, jotka ovat muutamaa minuuttia vanhempia.

Allekirjoituksen tarkistus komentorivillä:

expected="sha256=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')"
[ "$expected" = "$SIGNATURE" ] && echo "valid"

Kojelaudan yhteenveto

GET /dashboard palauttaa yleisnäkymän ruutujen takana olevat luvut: valvonnat tilan mukaan (palvelimet lasketaan pakettiyksikköinensä), palvelimet tilan mukaan ja avointen häiriöiden määrä. Pääsyn antaa mikä tahansa oikeuksista monitors:read, servers:read tai incidents:read.

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
  }
}

Usein kysytyt kysymykset

Mikä paketti sisältää API:n?

API-tokenit kuuluvat Business-paketista alkaen. Pienemmissä paketeissa näet osion kohdassa Oma tili harmaana ja päivityslinkin kera. Kaikki muu Centoculuksessa toimii ilman API:a.

Voiko yksi token tehdä kaiken, minkä tilini voi?

Ei. Token yltää vain alueisiin, joihin olet antanut sille oikeudet, eikä koskaan laskutukseen, tiimin jäseniin, muihin tokeneihin, tilin tietoturvaan tai korjauksiin (fixes). Ne pysyvät sovelluksessa.

Onko hiekkalaatikkoa?

Käytä tutustumiseen tokenia, jolla on vain lukuoikeudet, ja luo testivalvonnat toisen tilin ilmaispaketissa. Luomasi valvonnat lasketaan pakettiisi samalla tavalla kuin sovelluksessa luodut.

Miten saan hälytykset omaan järjestelmääni?

Luo webhook-kanava ja varmista jokaisen toimituksen allekirjoitus. Jokainen katko, palautuminen ja keskeytys saapuu URL-osoitteeseesi sekunneissa, ja valvonta, syy ja kohteena olleet sijainnit tulevat JSONina.

Muuttuuko API?

Versio on osoitteessa (/api/v1). Vastauksiin voidaan lisätä uusia kenttiä milloin tahansa; kenttiä ei poisteta eikä nimetä uudelleen version sisällä. Lue tarvitsemasi ja ohita loput.

Valmis automatisoimaan valvontasi?

API-tokenit sisältyvät Business-pakettiin ja sitä suurempiin. Vertaa paketteja tai aloita ilmaiseksi ja päivitä, kun skriptisi ovat valmiita.