이벤트·웹훅 도구
이 도구들은 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_id | string | 아니오 | 특정 서버로 이벤트를 필터링(서버 UUID) |
reporter | string | 아니오 | 리포터로 이벤트를 필터링 |
limit | integer | 아니오 | 반환할 최대 이벤트 수(기본값: 50) |
예시
“web-01에서 지난 하루 동안 무슨 일이 있었어?”
클라이언트는 server_id를 해당 서버의 UUID로 설정해 list_events를 호출하고, 반환된 활동을 요약합니다.
get_event
ID로 특정 이벤트의 전체 상세 정보(설명, 타임스탬프, 연관 서버, 리포터, 이벤트 레코드)를 조회합니다. list_events나 search_events로 관심 있는 이벤트를 찾은 뒤 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
event_id | string | 예 | 조회할 이벤트 ID |
예시
“방금 그 커밋 이벤트의 전체 상세 정보를 보여줘.”
클라이언트는 해당 이벤트 ID로 get_event를 호출해 전체 레코드를 반환합니다.
search_events
서버 이름, 리포터, 레코드, 설명 필드를 대상으로 키워드 검색을 수행합니다. 특정 서버로 검색 범위를 제한할 수도 있습니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
search_query | string | 예 | 검색할 키워드 |
server_id | string | 아니오 | 특정 서버로 검색 범위를 제한(서버 UUID) |
limit | integer | 아니오 | 반환할 최대 결과 수(기본값: 20) |
예시
“db-01에서 sudo와 관련된 이벤트 로그를 검색해줘.”
클라이언트는 search_query="sudo"와 db-01의 UUID로 설정한 server_id를 넣어 search_events를 호출합니다.
이벤트 구독
이벤트 구독은 어떤 이벤트(command_fin, servers_commit, sudo)가 발생했을 때 웹훅 같은 채널로 알림을 보낼지 정의합니다. 각 사용자는 자신의 구독만 관리할 수 있습니다.
list_event_subscriptions
워크스페이스의 이벤트 구독 목록(구독 ID, 채널, 이벤트 유형, 대상 ID)을 조회합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page | integer | 아니오 | 페이지네이션을 위한 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“내가 현재 설정해 둔 이벤트 구독이 뭐야?”
클라이언트는 list_event_subscriptions를 호출해 각 구독의 채널과 이벤트 유형을 나열합니다.
create_event_subscription
특정 이벤트 유형이 발생했을 때 알림을 받도록 이벤트 구독을 생성합니다. 알림 채널 ID(예: list_webhooks로 조회한 웹훅 ID)와 이벤트 유형이 필요합니다. 특정 대상 리소스로 필터링하는 것은 선택 사항입니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
channel | string | 예 | 이벤트를 전달할 알림 채널 ID(예: 웹훅 ID) |
event_type | string | 예 | 구독할 이벤트 유형: command_fin, servers_commit, sudo 중 하나 |
target_id | string | 아니오 | 특정 대상 리소스 ID로 구독을 제한 |
예시
“우리 운영 웹훅을 sudo 이벤트에 구독시켜줘.”
클라이언트는 먼저 list_webhooks로 웹훅 ID를 찾은 뒤, channel을 그 ID로, event_type="sudo"로 설정해 create_event_subscription을 호출합니다.
delete_event_subscription
ID로 이벤트 구독을 삭제해 해당 이벤트 유형의 알림을 더 이상 받지 않도록 합니다. 자신의 구독만 삭제할 수 있습니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
subscription_id | string | 예 | 삭제할 이벤트 구독 ID |
예시
“운영 웹훅으로 가는 sudo 알림을 그만 보내줘.”
클라이언트는 list_event_subscriptions로 해당 구독을 찾은 뒤 그 ID로 delete_event_subscription을 호출합니다.
웹훅
웹훅은 구독한 이벤트가 발생했을 때 HTTP 콜백을 받는 엔드포인트입니다. 웹훅 조회, 생성, 수정, 삭제 모두 관리자 권한이 필요합니다.
list_webhooks
워크스페이스에 설정된 웹훅 목록(웹훅 ID, 이름, URL, SSL 검증 설정, 활성화 상태)을 조회합니다. 관리자 권한이 필요합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page | integer | 아니오 | 페이지네이션을 위한 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“이 워크스페이스에 설정된 웹훅을 전부 보여줘.”
클라이언트는 list_webhooks를 호출해 각 웹훅의 이름, URL, 활성화 상태를 반환합니다.
get_webhook
ID로 특정 웹훅의 상세 정보(이름, URL, SSL 검증 설정, 활성화 상태, 소유자)를 조회합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
webhook_id | string | 예 | 조회할 웹훅 ID |
예시
“운영 웹훅의 상세 정보를 보여줘.”
클라이언트는 해당 웹훅 ID로 get_webhook을 호출해 전체 설정을 반환합니다.
create_webhook
구독한 이벤트가 발생했을 때 HTTP 콜백을 받을 웹훅 엔드포인트를 생성합니다. 이름과 URL이 필요하며, SSL 검증과 활성화 상태는 선택 사항입니다. 관리자 권한이 필요합니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | string | 예 | 웹훅 이름 |
url | string | 예 | 웹훅 콜백을 받을 URL |
ssl_verify | boolean | 아니오 | 콜백 URL의 SSL 인증서 검증 여부(기본값: true) |
enabled | boolean | 아니오 | 웹훅 활성화 여부(기본값: true) |
예시
“인시던트 봇 URL로 연결되는 ‘ops-alerts’라는 웹훅을 만들어줘.”
클라이언트는 name="ops-alerts"와 주어진 url로 create_webhook을 호출합니다.
update_webhook
ID로 기존 웹훅의 설정을 수정합니다. 지정한 필드만 수정되는 부분 업데이트입니다. 관리자 권한이 필요합니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
webhook_id | string | 예 | 수정할 웹훅 ID |
name | string | 아니오 | 새 웹훅 이름 |
url | string | 아니오 | 새 콜백 URL |
ssl_verify | boolean | 아니오 | 콜백 URL의 SSL 인증서 검증 여부 |
enabled | boolean | 아니오 | 웹훅 활성화 여부 |
예시
“ops-alerts 웹훅을 일단 비활성화해줘.”
클라이언트는 해당 웹훅 ID와 enabled=false로 update_webhook을 호출합니다.
delete_webhook
ID로 웹훅 엔드포인트를 영구 삭제합니다. 이 웹훅을 사용하는 구독의 모든 HTTP 콜백이 중단됩니다. 관리자 권한이 필요합니다.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
webhook_id | string | 예 | 삭제할 웹훅 ID |
예시
“예전 ops-alerts 웹훅은 더 이상 안 쓰니까 삭제해줘.”
클라이언트는 해당 웹훅 ID로 delete_webhook을 호출합니다. 이 웹훅을 가리키던 구독은 더 이상 알림을 전달하지 못합니다.
관련 문서
- 모니터링·알림 도구: 메트릭, 알림 규칙, 알림 관리
- 감사 로그 도구: 활동 로그, 서버 로그, WebFTP 전송 로그