업타임 모니터링 API
앱에서 하는 모든 작업을 REST API로도 할 수 있습니다. 배포 파이프라인에서 모니터를 만들고, 가동률과 응답 시간을 자체 대시보드로 가져오고, 상태 페이지와 알림 채널을 항상 동기화해 두세요. 입력도 출력도 JSON이며 Bearer 토큰 하나면 됩니다. API 토큰은 Business 요금제 이상에서 제공합니다.
시작하기
기본 URL
https://app.centoculus.com/api/v1
모든 요청에는 두 개의 헤더가 필요합니다. Authorization: Bearer <token>과 Accept: application/json입니다. 본문이 있는 요청은 Content-Type: application/json과 함께 JSON을 보냅니다.
- 웹 앱 또는 모바일 앱의 내 계정 → API 토큰에서 토큰을 만들고 스코프를 선택합니다.
- 토큰은 한 번만 표시되므로 바로 복사하세요.
GET /me를 호출합니다. 모든 토큰에서 동작하며 해당 토큰이 누구의 것인지 알려 줍니다.
첫 번째 호출:
curl https://app.centoculus.com/api/v1/me \
-H "Authorization: Bearer $CENTOCULUS_TOKEN" \
-H "Accept: application/json"
응답은 역할, 언어, 토큰이 접근할 수 있는 워크스페이스를 포함한 사용자 정보입니다(축약).
{
"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
}
}
토큰과 스코프
토큰에는 이름, 선택 사항인 만료일(최대 730일), 사용할 수 있는 스코프가 있습니다. 연동에 필요한 스코프만 선택하세요. 대시보드에는 monitors:read와 incidents:read, 배포 스크립트에는 monitors:write를 부여합니다. Business 미만 요금제에서는 이 섹션이 보이지만 비활성화되어 있습니다.
| 스코프 | 허용 범위 |
|---|---|
monitors:read | 모니터 목록과 상세, 가동률, 일별 가동률, 응답 시간, 체크 유형, 위치, 대시보드 요약 |
monitors:write | 모니터 생성, 수정, 삭제, 일시 중지, 재개 |
servers:read | 서버 목록과 상세, 서버 메트릭 |
servers:write | 서버 생성, 수정, 삭제, 일시 중지, 재개, 에이전트용 새 설치 명령 |
incidents:read | 인시던트 목록과 상세, 대시보드 요약 |
status-pages:read | 상태 페이지 목록과 상세 |
status-pages:write | 상태 페이지와 공지의 생성, 수정, 삭제 |
notifications:read | 알림 채널과 채널 유형의 목록과 상세 |
notifications:write | 채널(이메일, Telegram, Webhook, 푸시) 생성, 수정, 삭제, 테스트 발송 |
GET /me는 모든 토큰에서 동작합니다. 결제, 팀, 토큰, 계정 보안, 복구는 API 토큰으로 접근할 수 없으며 403을 반환합니다. 해당 스코프가 없는 호출도 마찬가지입니다.
토큰은 같은 곳에서 폐기할 수 있으며, 폐기 즉시 사용할 수 없게 됩니다.
공통 규칙
- 응답은 JSON입니다. 단일 객체는
data에, 목록은data에 담기며links와meta가 함께 옵니다. - 모니터와 서버는 UUID로, 인시던트, 상태 페이지, 알림 채널은 숫자 id로 지정합니다.
- 시각은 UTC 기준 ISO 8601 형식입니다. 예:
2026-11-15T08:30:00.000000Z. - 목록은 쿼리 매개변수
page와per_page로 페이지를 나눕니다.meta에는current_page,last_page,per_page,total이 들어 있습니다. 기본 페이지 크기: 모니터 15(최대 200), 인시던트 25(최대 100), 알림 채널 50, 서버 100, 상태 페이지 15. - 워크스페이스가 여러 개인 계정(파트너와 리셀러)은 생성할 때
customer_id를 전달하며, 목록을 필터링할 때도 사용할 수 있습니다. 고객 계정은 생략합니다. - 전체 요청 한도는 없습니다. 일부 엔드포인트에는 호출 제한이 있으며, 예를 들어 이메일 확인 재발송은 분당 10회입니다. 초과하면
Retry-After와 함께 429를 반환합니다. 체크 간격보다 자주 폴링하지 마세요. 실시간 데이터에는 Webhook 채널을 사용하세요.
오류
오류는 message가 담긴 JSON으로 반환됩니다. 유효성 검사 오류에는 필드별 메시지 목록을 담은 errors가 추가됩니다.
| 상태 | 의미 |
|---|---|
401 | 토큰이 없거나, 유효하지 않거나, 만료되었거나, 폐기되었습니다. |
402 | 선불 잔액을 모두 사용하여 모니터링이 일시 중지되었습니다(리셀러 고객). 충전하면 재개됩니다. |
403 | 토큰에 필요한 스코프가 없거나, API 토큰에 열려 있지 않은 엔드포인트이거나, 요금제에 해당 기능이 포함되어 있지 않습니다. |
404 | 찾을 수 없거나 내 워크스페이스에 없습니다. |
409 | 충돌입니다. 예를 들어 이미 확인된 이메일 주소를 다시 확인하려는 경우입니다. |
422 | 유효성 검사에 실패했습니다. errors를 확인하세요. 요금제 한도에 도달하면 upgrade에 상위 요금제에서 열리는 기능이 표시됩니다. |
429 | 호출 제한이 있는 엔드포인트에 요청이 너무 많습니다. Retry-After 초만큼 기다리세요. |
유효성 검사 오류 예시:
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."]
}
}
모니터
모니터는 하나의 체크입니다. 웹사이트, SSL 인증서, 핑, TCP 포트, DNS 레코드, cron 하트비트, 도메인의 메일 설정이 대상입니다. 유형: http, ssl, ping, tcp, dns, heartbeat, maildns, mailflow. GET /check-types는 요금제에 포함된 유형, 간격, 위치와 각 유형의 기본값을 알려 줍니다.
| 엔드포인트 | 기능 |
|---|---|
GET /monitors |
목록. 필터 status, search, ids(쉼표로 구분). with_stats=1을 쓰면 가동률과 마지막 응답 시간이 추가됩니다 |
POST /monitors |
생성. 체크는 백그라운드에서 시작됩니다 |
GET /monitors/{id} |
모니터 하나. 위치와 진행 중인 인시던트를 포함합니다 |
PATCH /monitors/{id} |
수정. 유형은 바꿀 수 없습니다 |
DELETE /monitors/{id} |
삭제(204) |
POST /monitors/{id}/pause |
일시 중지. 진행 중인 인시던트는 종료됩니다 |
POST /monitors/{id}/resume |
재개 |
GET /check-types |
유형, 기본값, 요금제의 한도 |
GET /locations |
활성 체크 위치(code, name, country) |
생성 시 필드
| 필드 | 설명 |
|---|---|
name |
표시 이름. 최대 255자. 필수. |
type |
위에 나열한 유형 중 하나. 필수이며 이후 변경할 수 없습니다. |
target |
유형에 따라 URL, 호스트 이름, IP 주소, 도메인 중 하나. heartbeat를 제외하고 필수이며, heartbeat는 대신 핑 URL이 발급됩니다. |
interval_seconds |
체크 간격. 최솟값은 요금제에 따라 다르며 GET /check-types가 limits.min_interval_seconds로 반환합니다. |
locations |
위치 코드. 예: ["eu", "sg"]. 선택할 수 있는 개수는 요금제에 따라 다릅니다. |
primary_location |
장애를 가장 먼저 확인하는 기본 위치(Smart Verify). |
confirm_locations |
알림을 보내기 전에 몇 곳의 위치에서 실패를 확인해야 하는지(1–3). 상위 요금제에서 설정할 수 있습니다. |
confirm_checks |
몇 번 연속으로 체크에 실패하면 장애로 확정하는지(1–3). 상위 요금제에서 설정할 수 있습니다. |
options |
유형별 옵션. http의 경우: method(GET, HEAD, POST), expected_status(예: 200-399 또는 200,301), keyword와 keyword_mode(present 또는 absent), timeout_seconds, check_ssl, warn_days, crit_days, allow_self_signed. 생략한 옵션은 GET /check-types의 기본값을 따릅니다. |
키워드가 있는 웹사이트 체크 생성:
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"}
}'
응답(201)은 모니터입니다. 위치에서 모니터를 넘겨받으면 provisioning.state가 synced로, 첫 체크 후 status가 pending에서 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"
}
}
상태 값: pending, up, degraded, down, paused.
배포 중에는 모니터를 일시 중지하고, 끝나면 재개합니다:
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"
가동률과 응답 시간
가동률은 장애(심각도 major인 인시던트)를 기준으로 계산합니다. 인증서 만료 임박 같은 경고는 포함되지 않습니다. 아직 체크하지 않았다면 100이 아니라 null입니다.
| 엔드포인트 | 기능 |
|---|---|
GET /monitors/{id}/uptime |
최근 24시간, 7일, 30일의 가동률(퍼센트) |
GET /monitors/{id}/daily-uptime |
달력 날짜(UTC)별 가동률. days는 1–90, 기본값 30 |
GET /monitors/{id}/response-times |
위치별 응답 시간과 가용성. range는 24h, 7d, 30d. 시간 단위 데이터 포인트이며 30d는 일 단위 |
가동률:
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}}
응답 시간(축약):
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}
]
}
}
}
서버
서버는 에이전트가 설치된 장비로, CPU, 메모리, 부하, 디스크, 네트워크, 서비스를 보고합니다. 서버를 생성하면 일회용 설치 명령이 반환됩니다. 장비에서 실행하면 잠시 후 서버가 나타납니다.
| 엔드포인트 | 기능 |
|---|---|
GET /servers |
목록. 필터 ids |
POST /servers |
생성. 응답에 install_command(Linux)와 install_command_freebsd가 포함됩니다 |
GET /servers/{id} |
서버 하나. 인벤토리, 최신 스냅샷, 임계값을 포함합니다 |
PATCH /servers/{id} |
이름 변경, 감시할 services 선택, thresholds 설정 |
DELETE /servers/{id} |
삭제(204). 에이전트는 모니터링에서 제외됩니다 |
POST /servers/{id}/pause |
일시 중지. 진행 중인 인시던트는 종료됩니다 |
POST /servers/{id}/resume |
재개 |
POST /servers/{id}/install-token |
새 설치 명령. rotate_key=true를 쓰면 에이전트 키도 새로 발급합니다 |
GET /servers/{id}/metrics |
차트용 시계열. range는 24h, 7d, 30d: 메트릭 → 컨텍스트 → [unix time, avg, min, max] |
| 필드 | 설명 |
|---|---|
name |
표시 이름. 최대 100자. 생성 시 필수. |
services |
에이전트가 감시할 서비스 이름. 예: ["nginx", "php8.4-fpm", "mariadb"]. 최대 200개. 서버가 찾아낸 서비스는 discovered.services로 보고됩니다. |
thresholds |
알림 임계값: cpu_max(퍼센트), load_max_per_cpu, mem_min_pavail(여유 퍼센트), fs_warn과 fs_crit(사용 퍼센트), inode_warn, agent_nodata_minutes, 마운트 지점별 filesystems, 정규식 fs_types, fs_exclude, net_exclude. 생략한 값은 기본값을 유지합니다. |
서버를 추가하고 응답에서 설치 명령 읽기:
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"
}
}
서비스 세 개를 감시하고 디스크 사용량 80퍼센트에서 알림 보내기:
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}
}'
인시던트
인시던트는 모니터나 서버에서 발생한 한 번의 장애 또는 경고이며, started_at부터 resolved_at까지입니다. 모든 인시던트에는 알림 번호가 있으며, 알림 이메일에 표시되는 번호와 같습니다.
| 엔드포인트 | 기능 |
|---|---|
GET /incidents |
최신순. 필터 monitor_id, status(open 또는 closed), open=1(공지를 제외한 진행 중인 장애), from과 to(날짜) |
GET /incidents/{id} |
인시던트 하나와 타임라인. 어느 위치가 언제 다운되고 복구되었는지, 이를 처리한 복구 작업을 포함합니다 |
진행 중인 인시던트:
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}
}
주요 필드: subject_type(monitor 또는 server), severity(major, warning, info), cause(예: unreachable, network_issue, certificate_expiring, heartbeat_missed), duration_seconds, affected_locations, 그리고 진행 중일 때는 최근 체크 값이 담긴 failure_reason.
상태 페이지
상태 페이지는 선택한 모니터를 일반에 공개하거나 팀에게 보여 줍니다. 당사 도메인이나 고객님의 도메인에서 운영할 수 있습니다. 공지는 점검을 알리거나 진행 중인 인시던트를 설명할 때 사용합니다.
| 엔드포인트 | 기능 |
|---|---|
GET /status-pages |
목록 |
POST /status-pages |
생성 |
GET /status-pages/{id} |
페이지 하나. 모니터, 공지, 도메인 상태를 포함합니다 |
PATCH /status-pages/{id} |
수정. monitors는 목록 전체를 교체합니다 |
DELETE /status-pages/{id} |
삭제(204) |
POST /status-pages/{id}/notices |
공지 추가 |
PUT /status-pages/{id}/notices/{notice} |
공지 수정 |
DELETE /status-pages/{id}/notices/{notice} |
공지 삭제(204) |
| 필드 | 설명 |
|---|---|
slug |
주소의 일부. 3–63자의 소문자, 숫자, 하이픈. 고유해야 합니다. 필수. |
title |
페이지 제목. 필수. |
description |
제목 아래에 표시되는 짧은 문구. 최대 2000자. |
logo_url |
로고의 HTTPS 주소. |
custom_domain |
status.example.com 같은 자체 도메인. 자체 상태 도메인을 지원하는 요금제가 필요합니다. |
is_public |
공개(true) 또는 로그인한 사용자 전용. |
monitors |
{"id": "<monitor UUID>", "display_name": "…", "group": "…"}의 순서 있는 목록. display_name과 group은 선택 사항입니다. |
공지에는 kind(maintenance, info, incident), title, body(선택, 최대 5000자), starts_at, 선택 사항인 ends_at이 있습니다.
모니터 두 개가 있는 공개 상태 페이지 생성:
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"}
]
}'
점검 시간 공지:
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"
}'
알림 채널
알림 채널은 누군가에게 연락하는 한 가지 방법입니다. 이메일 주소, Telegram 채팅, Webhook, 사용자의 푸시 기기가 해당합니다. 채널은 워크스페이스의 모든 모니터 알림을 받거나, monitor_ids에 지정한 모니터의 알림만 받습니다. 요금제에 포함된 채널 유형은 GET /notification-channel-types로 확인합니다.
| 엔드포인트 | 기능 |
|---|---|
GET /notification-channels |
목록 |
POST /notification-channels |
생성. Webhook의 서명용 secret은 이 응답에만 포함됩니다 |
GET /notification-channels/{id} |
채널 하나 |
PATCH /notification-channels/{id} |
수정. 유형은 바꿀 수 없습니다 |
DELETE /notification-channels/{id} |
삭제(204) |
POST /notification-channels/{id}/test |
테스트 알림 발송(202). 확인되지 않은 이메일 주소에는 대신 확인 링크가 다시 발송됩니다 |
GET /notification-channel-types |
available과 paid가 포함된 채널 유형 |
| 필드 | 설명 |
|---|---|
type |
email, telegram, webhook, push 중 하나. 필수이며 이후 변경할 수 없습니다. |
name |
표시 이름. 필수. |
config |
유형별로 {"email": "…"}, {"chat_id": "…"}, {"url": "https://…"}. 푸시는 config가 필요 없습니다. 새 이메일 주소는 알림이 발송되기 전에 링크로 확인해야 합니다. |
monitor_ids |
이 채널이 담당할 모니터의 UUID. 생략하면 모든 모니터가 대상입니다. |
quiet_hours |
{"start": "22:00", "end": "07:00", "timezone": "Europe/Berlin"}: 이 시간대에는 알림을 보내지 않습니다. |
escalation_delay_minutes |
장애가 이 시간만큼 지속될 때만 이 채널로 알립니다(0–1440). |
notify_recovery |
복구 알림도 보낼지 여부(true 또는 false). |
is_active |
삭제하지 않고 채널을 켜거나 끕니다. |
모니터 두 개용 Webhook 채널을 만들고 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"
}
}
Webhook 페이로드
Webhook 채널은 모든 알림을 JSON으로 고객님의 URL에 POST합니다. 제한 시간은 10초이며 리다이렉트는 따라가지 않습니다. 대상은 공개 주소여야 합니다.
헤더: X-Webhook-Timestamp(Unix 시간), X-Webhook-Signature(sha256= 뒤에 채널 secret을 키로 한 <timestamp>.<body>의 HMAC-SHA256), User-Agent: Uptime-Webhook/1.
event는 down, recovered, paused, test 중 하나입니다. 모니터 알림의 본문에는 monitor(id, name, target)와 incident(id, severity, cause, started_at, resolved_at, duration_seconds, affected_locations)가 들어 있습니다. 서버 알림에는 server(id, name)와, 위치 대신 problem이 있는 incident가 들어 있습니다. subject는 채널 언어로 된 알림 제목입니다.
다운 알림의 본문:
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"
}
본문을 신뢰하기 전에 서명을 검증하세요. 받은 원본 본문 그대로 HMAC을 계산하고 상수 시간으로 비교합니다. 몇 분보다 오래된 타임스탬프는 거부하세요.
셸에서 서명 확인:
expected="sha256=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')"
[ "$expected" = "$SIGNATURE" ] && echo "valid"
대시보드 요약
GET /dashboard는 개요 화면의 타일에 쓰이는 수치를 반환합니다. 상태별 모니터 수(서버는 요금제 단위로 계산), 상태별 서버 수, 진행 중인 인시던트 수입니다. monitors:read, servers:read, 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
}
}
자주 묻는 질문
API는 어떤 요금제에 포함되나요?
API 토큰은 Business 요금제 이상에서 제공합니다. 그보다 낮은 요금제에서는 내 계정에 이 섹션이 비활성화된 상태로 표시되며 업그레이드 링크가 함께 보입니다. Centoculus의 나머지 기능은 API 없이도 모두 사용할 수 있습니다.
토큰 하나로 내 계정이 할 수 있는 모든 일을 할 수 있나요?
아니요. 토큰은 스코프를 부여한 영역에만 접근할 수 있으며, 결제, 팀원, 다른 토큰, 계정 보안, 복구에는 접근할 수 없습니다. 이 기능들은 앱에서 이용하세요.
샌드박스가 있나요?
살펴볼 때는 읽기 스코프만 있는 토큰을 사용하고, 테스트용 모니터는 다른 계정의 무료 요금제에서 만드세요. 직접 만든 모니터는 앱에서 만든 것과 똑같이 요금제의 모니터 수에 포함됩니다.
알림을 자체 시스템으로 받으려면 어떻게 하나요?
Webhook 채널을 만들고 전송마다 서명을 검증하세요. 모든 장애, 복구, 일시 중지가 모니터, 원인, 영향받은 위치와 함께 JSON으로 몇 초 안에 고객님의 URL로 전달됩니다.
API가 바뀌기도 하나요?
버전은 주소(/api/v1)에 들어 있습니다. 응답에 새 필드가 언제든 추가될 수 있지만, 같은 버전 안에서 필드를 제거하거나 이름을 바꾸지는 않습니다. 필요한 것만 읽고 나머지는 무시하세요.
모니터링 자동화를 시작해 보시겠어요?
API 토큰은 Business 요금제 이상에 포함되어 있습니다. 요금제를 비교하거나, 무료로 시작해 스크립트가 준비되면 업그레이드하세요.