외부 채널

지원하는 채널

• 모든 채널 주소는 https://여야 합니다.
• 조직당 채널은 10개까지 연결할 수 있습니다. 꺼진 채널도 개수에 포함됩니다.
• 저장한 주소는 다시 전체를 보여 주지 않고 앞뒤 일부만 표시합니다.

채널 연결하기

1. 콘솔에서 알림을 열고 외부 채널 탭을 선택합니다. 조직 설정의 외부 채널 카드에서도 들어갈 수 있습니다.
2. 채널 연결을 누릅니다.
3. 채널 주소를 붙여 넣습니다. Slack·Discord 주소는 종류가 자동으로 선택됩니다. 주소를 만드는 방법은 입력 칸 옆의 주소 만드는 법에서 확인할 수 있습니다.
4. 보낼 알림과 옵션을 고릅니다.
5. 테스트 메시지 보내기로 채널에 메시지가 오는지 확인한 뒤 저장합니다.

보낼 알림 고르기

보낼 수 있는 알림

• 로그 알림: 채널 구독과 관계없이, 규칙에서 고른 채널로만 보냅니다.
• 나에게만 오는 알림: 요청 접수·처리 결과, 내 의견에 대한 답변.
• 서비스 공지와 외부 채널 연동 꺼짐 알림.

특정 프로젝트만 보내기

메시지 옵션

• 메시지 언어: 한국어 또는 English를 고릅니다. 기본값은 조직 지역(미국이면 English, 그 외는 한국어)이며, 채널마다 저장되므로 나중에 조직 지역을 바꿔도 기존 채널의 언어는 그대로입니다. 메시지의 시각은 한국어면 KST, 영어면 UTC로 표시됩니다.
• 장애 알림에 @here 멘션 붙이기: Slack·Discord 채널에서 장애(빨간색) 알림에 @here를 붙입니다. 기본은 꺼져 있습니다.
• 로그 줄과 배포 실패 사유 포함: 로그 알림의 맞은 로그와 배포 실패 원인을 메시지에 함께 보냅니다. 기본은 켜져 있습니다. 끄면 제목과 콘솔 링크만 보내므로, 로그에 민감한 값이 찍힐 수 있다면 꺼 두세요.

메시지 모양

• 카드 색은 알림의 심각도를 나타냅니다 — 장애(빨강), 경고(주황), 완료(초록), 안내(회색).
• 제목과 내용 아래에 로그 알림의 맞은 로그(최대 5줄)나 배포 실패 원인이 코드 블록으로 붙습니다.
• 컨테이너 보기, 로그 보기, 결제 보기처럼 콘솔의 해당 화면으로 가는 링크가 붙습니다.
• 맨 아래에 AirCloud · {조직 이름}이 표시됩니다.

웹훅 받기

요청

본문

{
  "id": "6f1c2b0e-2d4a-4a57-9c3e-0b8f0d6a1e42",
  "type": "endpoint.deploy_failed",
  "version": 1,
  "created_at": "2026-11-03T05:12:33.123456+00:00",
  "severity": "error",
  "organization": { "id": "org-xxxxxxxxxxxx", "name": "Acme" },
  "title": "컨테이너 'my-llm' 배포에 실패했습니다",
  "text": null,
  "url": "https://…/console/projects/…/container/…",
  "data": { "endpoint_id": "…", "endpoint_name": "my-llm", "project_id": "…" },
  "detail": "RuntimeError: …"
}

서명 검증

• 본문은 받은 그대로의 바이트로 검증하세요. JSON을 파싱했다가 다시 직렬화하면 서명이 맞지 않습니다.
• webhook-timestamp가 너무 오래된 요청(예: 5분 이상)은 버려 재전송 공격을 막으세요.
• 언어별 공식 라이브러리를 쓰면 검증을 직접 구현하지 않아도 됩니다.

import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60


def verify(secret: str, headers: dict, body: bytes) -> bool:
    msg_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]
    signature = headers["webhook-signature"]

    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for item in signature.split(" "):
        version, _, value = item.partition(",")
        if version == "v1" and hmac.compare_digest(value, expected):
            return True
    return False

응답과 재시도

• 성공: 2xx로 응답하면 전송된 것으로 봅니다. 10초 안에 응답해야 하며, 리다이렉트는 따라가지 않습니다.
• 재시도: 응답이 없거나 실패하면 30초, 2분, 10분, 30분, 1시간, 2시간 간격으로 다시 보냅니다(처음 시도 포함 최대 7번, 약 4시간). 처음 만든 지 6시간이 지난 전송은 더 보내지 않습니다.
• Retry-After: 응답에 Retry-After 헤더가 있으면 그만큼 기다렸다가 보냅니다(최대 30분).
• 중복 거르기: 같은 알림이 두 번 이상 도착할 수 있습니다. webhook-id로 중복을 거르세요.

전송 기록과 다시 보내기

• 최근 전송 기록: 최근 50건을 보여 주며, 기록은 30일 동안 보관합니다. 상태는 대기, 전송됨, 실패, 건너뜀 중 하나입니다.
• 다시 보내기: 실패한 전송만 다시 보낼 수 있습니다. 다시 보내면 재시도 주기가 처음부터 시작되며, webhook-id는 그대로입니다.
• 테스트 메시지는 전송 기록에 남지 않고, @here 멘션도 붙지 않습니다.

채널이 자동으로 꺼지는 경우

• 채널이 꺼지면 조직 전체에 외부 채널 연동 꺼짐 알림이 가고, 조직 소유자에게 메일이 발송됩니다.
• 꺼지는 시점에 대기 중이던 전송은 건너뜀이 됩니다. 꺼져 있는 동안 생긴 알림은 나중에 다시 켜도 보내지 않습니다.
• 다시 켜려면 채널 상세 화면의 스위치를 켭니다. 주소를 바꾸는 것만으로는 채널이 켜지지 않습니다.
• 직접 끄거나 삭제한 경우에는 알림을 보내지 않습니다.

서명 키 다시 만들기

권한

주소 제한

• https:// 주소만 쓸 수 있고, 주소에 사용자 이름·비밀번호를 넣을 수 없습니다.
• localhost, .local, .internal 같은 내부 이름과 사설·루프백·링크 로컬 IP 주소는 쓸 수 없습니다.
• 보낼 때마다 주소를 다시 확인해, 내부망 주소로 풀리면 보내지 않고 채널을 끕니다.

연결 끊기

관련 문서