이벤트·웹훅 도구

이 도구들은 Alpacon의 이벤트 시스템을 다룹니다. 서버 활동을 기록하는 이벤트 로그를 조회·검색하고, 이벤트 구독과 웹훅 엔드포인트를 통해 AI 클라이언트 밖으로 이벤트를 전달하는 방법을 설정합니다. “web-01에서 지난 하루 동안 무슨 일이 있었는지”, “서버 설정이 바뀌면 Slack 웹훅으로 알려줘”, “그 채널로 sudo 알림 그만 보내줘” 같은 요청이 모두 이 페이지의 도구로 이어집니다.

참고

모든 도구는 workspace(필수)와 region(선택, 미지정 시 설정된 리전 사용)을 받습니다. 아래 표에서는 이 공통 파라미터를 생략합니다.

요약

도구설명접근 수준
list_events최신순으로 최근 서버 이벤트 조회읽기 전용
get_event특정 이벤트의 상세 정보 조회읽기 전용
search_events키워드로 이벤트 검색읽기 전용
list_event_subscriptions이벤트 구독 목록 조회읽기 전용
create_event_subscription알림 채널을 이벤트 유형에 구독 등록추가적
delete_event_subscription이벤트 구독 삭제파괴적
list_webhooks설정된 웹훅 목록 조회읽기 전용
get_webhook특정 웹훅의 상세 정보 조회읽기 전용
create_webhook웹훅 엔드포인트 생성추가적
update_webhook웹훅 설정 수정멱등적 쓰기
delete_webhook웹훅 영구 삭제파괴적

이벤트

명령 완료, 커밋, sudo 사용 같은 서버 활동을 기록하는 이벤트 로그를 조회하는 읽기 전용 도구입니다.

list_events

최근 서버 이벤트와 활동 로그를 최신순으로 조회합니다. 서버나 리포터로 필터링해 로그 범위를 좁힐 수 있습니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
server_idstring아니오특정 서버로 이벤트를 필터링(서버 UUID)
reporterstring아니오리포터로 이벤트를 필터링
limitinteger아니오반환할 최대 이벤트 수(기본값: 50)

예시

“web-01에서 지난 하루 동안 무슨 일이 있었어?”

클라이언트는 server_id를 해당 서버의 UUID로 설정해 list_events를 호출하고, 반환된 활동을 요약합니다.

get_event

ID로 특정 이벤트의 전체 상세 정보(설명, 타임스탬프, 연관 서버, 리포터, 이벤트 레코드)를 조회합니다. list_events나 search_events로 관심 있는 이벤트를 찾은 뒤 사용합니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
event_idstring예조회할 이벤트 ID

예시

“방금 그 커밋 이벤트의 전체 상세 정보를 보여줘.”

클라이언트는 해당 이벤트 ID로 get_event를 호출해 전체 레코드를 반환합니다.

search_events

서버 이름, 리포터, 레코드, 설명 필드를 대상으로 키워드 검색을 수행합니다. 특정 서버로 검색 범위를 제한할 수도 있습니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
search_querystring예검색할 키워드
server_idstring아니오특정 서버로 검색 범위를 제한(서버 UUID)
limitinteger아니오반환할 최대 결과 수(기본값: 20)

예시

“db-01에서 sudo와 관련된 이벤트 로그를 검색해줘.”

클라이언트는 search_query="sudo"와 db-01의 UUID로 설정한 server_id를 넣어 search_events를 호출합니다.

이벤트 구독

이벤트 구독은 어떤 이벤트(command_fin, servers_commit, sudo 등, 지표 알림 이벤트 두 가지는 지표 임계값 이벤트 참고)가 발생했을 때 웹훅 같은 채널로 알림을 보낼지 정의합니다. 각 사용자는 자신의 구독만 관리할 수 있습니다.

list_event_subscriptions

워크스페이스의 이벤트 구독 목록(구독 ID, 채널, 이벤트 유형, 대상 ID)을 조회합니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
pageinteger아니오페이지네이션을 위한 페이지 번호
page_sizeinteger아니오페이지당 항목 수

예시

“내가 현재 설정해 둔 이벤트 구독이 뭐야?”

클라이언트는 list_event_subscriptions를 호출해 각 구독의 채널과 이벤트 유형을 나열합니다.

create_event_subscription

특정 이벤트 유형이 발생했을 때 알림을 받도록 이벤트 구독을 생성합니다. 알림 채널 ID(예: list_webhooks로 조회한 웹훅 ID)와 이벤트 유형이 필요합니다. 특정 대상 리소스로 필터링하는 것은 선택 사항입니다.

접근 수준: 추가적

파라미터

파라미터타입필수설명
channelstring예이벤트를 전달할 알림 채널 ID(예: 웹훅 ID)
event_typestring예구독할 이벤트 유형입니다(예: command_fin, servers_commit, sudo, metric_threshold_crossed, metric_threshold_resolved). 이 도구는 값을 그대로 전달할 뿐, 지원되는 유형인지 검증하거나 목록으로 제공하지 않습니다
target_idstring아니오특정 대상 리소스 ID로 구독을 제한

예시

“우리 운영 웹훅을 sudo 이벤트에 구독시켜줘.”

클라이언트는 먼저 list_webhooks로 웹훅 ID를 찾은 뒤, channel을 그 ID로, event_type="sudo"로 설정해 create_event_subscription을 호출합니다.

delete_event_subscription

ID로 이벤트 구독을 삭제해 해당 이벤트 유형의 알림을 더 이상 받지 않도록 합니다. 자신의 구독만 삭제할 수 있습니다.

접근 수준: 파괴적

파라미터

파라미터타입필수설명
subscription_idstring예삭제할 이벤트 구독 ID

예시

“운영 웹훅으로 가는 sudo 알림을 그만 보내줘.”

클라이언트는 list_event_subscriptions로 해당 구독을 찾은 뒤 그 ID로 delete_event_subscription을 호출합니다.

지표 임계값 이벤트

경고 규칙의 경고를 channel이 가리키는 곳, 즉 웹훅을 비롯한 알림 채널로 전달하는 이벤트 유형이 두 가지 있습니다. 규칙의 임계값을 넘었을 때(또는 지표가 정해진 시간 동안 들어오지 않아 끊겼을 때) 오는 metric_threshold_crossed, 그 경고가 나중에 해제될 때 오는 metric_threshold_resolved입니다.

두 이벤트 모두 Metrics 확장 기능이 있어야 구독할 수 있습니다. Essentials와 Enterprise 워크스페이스는 켤 수 있고 Free는 켤 수 없습니다(서버 상태 모니터링 참고). 구독한 뒤 확장 기능을 끄면 그 구독에서는 metric_threshold_crossed를 더 이상 받지 못하지만 metric_threshold_resolved는 계속 받으므로, 이미 추적하던 경고는 항상 종료 이벤트를 받게 됩니다.

두 이벤트는 같은 alert_id를 갖고 있어서, 릴레이는 이 값으로 metric_threshold_resolved를 그 경고를 열었던 metric_threshold_crossed와 짝지을 수 있습니다.

metric_threshold_crossed

json
{
  "event": "metric_threshold_crossed",
  "alert_id": "9a1c0b62-9f3a-4a3d-8a1e-2b0f2c6d5e41",
  "reason": "threshold",
  "rule": {
    "id": "4f2b18d0-5c77-4a0b-9d2e-1f7a3c9b4e05",
    "name": "cpu-high",
    "target": "cpu-usage",
    "operator": "gte",
    "threshold": 80.0,
    "duration_s": 300,
    "severity": "warning"
  },
  "server": { "id": "7c5e2a41-6b90-4c33-a7d8-0e5f1b2c3d44", "name": "web-01" },
  "device": null,
  "observed": {
    "value": 92.3,
    "window_start": "2026-09-01T11:55:00+00:00",
    "window_end": "2026-09-01T11:59:30+00:00"
  },
  "started_at": "2026-09-01T12:00:00+00:00",
  "workspace": "acme",
  "link": "https://acme.ap1.alpacon.io/servers/7c5e2a41-6b90-4c33-a7d8-0e5f1b2c3d44"
}

metric_threshold_resolved

json
{
  "event": "metric_threshold_resolved",
  "alert_id": "9a1c0b62-9f3a-4a3d-8a1e-2b0f2c6d5e41",
  "reason": "threshold",
  "rule": {
    "id": "4f2b18d0-5c77-4a0b-9d2e-1f7a3c9b4e05",
    "name": "cpu-high",
    "target": "cpu-usage",
    "operator": "gte",
    "threshold": 80.0,
    "duration_s": 300,
    "severity": "warning"
  },
  "server": { "id": "7c5e2a41-6b90-4c33-a7d8-0e5f1b2c3d44", "name": "web-01" },
  "device": null,
  "observed": {
    "value": 41.2,
    "window_start": "2026-09-01T12:05:00+00:00",
    "window_end": "2026-09-01T12:05:00+00:00"
  },
  "started_at": "2026-09-01T12:00:00+00:00",
  "workspace": "acme",
  "link": "https://acme.ap1.alpacon.io/servers/7c5e2a41-6b90-4c33-a7d8-0e5f1b2c3d44",
  "cause": "recovered",
  "resolved_at": "2026-09-01T12:05:00+00:00",
  "open_for_s": 300
}

필드

필드의미
alert_id이 경고를 식별합니다. 경고를 연 metric_threshold_crossed와 닫는 metric_threshold_resolved에 같은 값이 실립니다.
reasonthreshold(규칙의 임계값을 넘었습니다) 또는 no_data(지표 수신이 끊겼습니다) 중 하나입니다.
rule이 알림을 발생시킨 규칙을 서버별 오버라이드까지 반영해서 담습니다: id, name, target(지켜보는 지표), operator(gte 또는 lte), threshold, duration_s, severity. 각 필드의 의미는 규칙에 설정할 수 있는 항목을 참고하세요. metric_threshold_resolved에서는 현재 시점의 규칙을 담으며, 규칙이 이미 삭제됐다면 null입니다. 무엇이 이 알림을 발생시켰는지는 같은 alert_id를 가진 metric_threshold_crossed 이벤트를 보세요.
server경고가 발생한 서버입니다: id, name.
device규칙이 특정 디스크나 네트워크 인터페이스로 범위가 좁혀져 있으면 그 이름이고, 호스트 전체를 대상으로 하는 규칙이면 null입니다.
observed이 판정에 쓰인 샘플입니다: value는 가장 최근 샘플이고, window_start/window_end는 실제로 읽은 샘플의 범위입니다. reason이 no_data면 null입니다.
started_at경고가 처음 발생한 시각입니다.
workspace워크스페이스 슬러그입니다.
link콘솔의 해당 서버 페이지입니다.
cause(resolved 전용)경고가 닫힌 이유입니다: recovered(지표가 복귀 임계값을 다시 충족함, 따로 설정하지 않았다면 규칙의 임계값 자체), no_data_cleared(서버가 다시 데이터를 보고하기 시작함), rule_detached(규칙이 삭제됐거나, 서버가 그 규칙에서 떨어져 나감), rule_changed 또는 scope_narrowed(규칙이 더 이상 이 서버나 장치를 대상으로 하지 않음), override_disabled(서버별 오버라이드로 제외됨), server_disabled(서버가 더 이상 관리되지 않음), not_evaluated(더 이상 어떤 규칙도 이 경고를 평가하지 않음), superseded(장치별 경고가 호스트 전체 경고를 대체함), device_removed(서버가 더 이상 이 장치를 보고하지 않음), unknown(더 구체적인 원인으로 추적할 수 없는 해제로, 조건이 더 이상 적용되지 않음).
resolved_at(resolved 전용)경고가 닫힌 시각입니다.
open_for_s(resolved 전용)경고가 열려 있던 시간(초)입니다. 경고가 발생하기까지 조건이 유지돼야 하는 시간인 rule.duration_s와는 다른 값이니 혼동하지 마세요.

웹훅

웹훅은 구독한 이벤트가 발생했을 때 HTTP 콜백을 받는 엔드포인트입니다. 웹훅 조회, 생성, 수정, 삭제 모두 관리자 권한이 필요합니다.

list_webhooks

워크스페이스에 설정된 웹훅 목록(웹훅 ID, 이름, URL, SSL 검증 설정, 활성화 상태)을 조회합니다. 관리자 권한이 필요합니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
pageinteger아니오페이지네이션을 위한 페이지 번호
page_sizeinteger아니오페이지당 항목 수

예시

“이 워크스페이스에 설정된 웹훅을 전부 보여줘.”

클라이언트는 list_webhooks를 호출해 각 웹훅의 이름, URL, 활성화 상태를 반환합니다.

get_webhook

ID로 특정 웹훅의 상세 정보(이름, URL, SSL 검증 설정, 활성화 상태, 소유자)를 조회합니다.

접근 수준: 읽기 전용

파라미터

파라미터타입필수설명
webhook_idstring예조회할 웹훅 ID

예시

“운영 웹훅의 상세 정보를 보여줘.”

클라이언트는 해당 웹훅 ID로 get_webhook을 호출해 전체 설정을 반환합니다.

create_webhook

구독한 이벤트가 발생했을 때 HTTP 콜백을 받을 웹훅 엔드포인트를 생성합니다. 이름과 URL이 필요하며, SSL 검증과 활성화 상태는 선택 사항입니다. 관리자 권한이 필요합니다.

접근 수준: 추가적

파라미터

파라미터타입필수설명
namestring예웹훅 이름
urlstring예웹훅 콜백을 받을 URL
ssl_verifyboolean아니오콜백 URL의 SSL 인증서 검증 여부(기본값: true)
enabledboolean아니오웹훅 활성화 여부(기본값: true)

예시

“인시던트 봇 URL로 연결되는 ‘ops-alerts’라는 웹훅을 만들어줘.”

클라이언트는 name="ops-alerts"와 주어진 url로 create_webhook을 호출합니다.

update_webhook

ID로 기존 웹훅의 설정을 수정합니다. 지정한 필드만 수정되는 부분 업데이트입니다. 관리자 권한이 필요합니다.

접근 수준: 멱등적 쓰기

파라미터

파라미터타입필수설명
webhook_idstring예수정할 웹훅 ID
namestring아니오새 웹훅 이름
urlstring아니오새 콜백 URL
ssl_verifyboolean아니오콜백 URL의 SSL 인증서 검증 여부
enabledboolean아니오웹훅 활성화 여부

예시

“ops-alerts 웹훅을 일단 비활성화해줘.”

클라이언트는 해당 웹훅 ID와 enabled=false로 update_webhook을 호출합니다.

delete_webhook

ID로 웹훅 엔드포인트를 영구 삭제합니다. 이 웹훅을 사용하는 구독의 모든 HTTP 콜백이 중단됩니다. 관리자 권한이 필요합니다.

접근 수준: 파괴적

파라미터

파라미터타입필수설명
webhook_idstring예삭제할 웹훅 ID

예시

“예전 ops-alerts 웹훅은 더 이상 안 쓰니까 삭제해줘.”

클라이언트는 해당 웹훅 ID로 delete_webhook을 호출합니다. 이 웹훅을 가리키던 구독은 더 이상 알림을 전달하지 못합니다.

관련 문서

최종 수정: