Cloudwiki/설정/웹훅

# Discord 웹훅 알림 설정 가이드

CloudWiki 는 위키에서 발생한 주요 이벤트(가입 신청, 티켓 작성, 신규 토론, 공지 발행 등)를 [Discord 웹훅](https://discord.com/developers/docs/resources/webhook) 으로 발송할 수 있습니다. 운영자/관리자용 알림과 일반 사용자에게 보여줄 커뮤니티 알림을 **두 채널** 로 분리 발송하며, 이벤트 화이트리스트로 발송 종류를 세밀하게 제어합니다.


---

## 채널 구조

CloudWiki 의 웹훅은 **admin** 과 **community** 두 채널로 분리되어 있습니다. 호출부는 채널을 모르고 이벤트만 발행하며, 채널 라우팅은 이벤트 객체의 `channel` 필드로 결정됩니다.

| 채널 | 용도 | 환경 변수 (URL) | 환경 변수 (이벤트 화이트리스트) |
|---|---|---|---|
| `admin` | 운영자만 보는 비공개 알림 (가입 신청, 차단, 권한 변경, 티켓 등) | `DISCORD_ADMIN_WEBHOOK_URL` | `DISCORD_ADMIN_EVENTS` |
| `community` | 일반 멤버가 함께 보는 커뮤니티 알림 (신규 가입 환영, 신규 토론, 공지 발행) | `DISCORD_COMMUNITY_WEBHOOK_URL` | `DISCORD_COMMUNITY_EVENTS` |

URL 이 비어 있으면 해당 채널은 **자동 비활성**, 화이트리스트가 비어 있으면 모든 이벤트가 차단됩니다.

웹훅의 표시 이름과 아바타는 `WIKI_NAME` / `WIKI_LOGO_URL` 을 재사용합니다. 로고 경로가 상대 경로(`/favicon.jpg` 등) 이면 `WIKI_PUBLIC_BASE_URL` 와 결합해 절대 URL 로 보정됩니다.

---

## 지원 이벤트

이벤트 키는 `DISCORD_ADMIN_EVENTS` / `DISCORD_COMMUNITY_EVENTS` 의 화이트리스트 항목과 정확히 일치해야 발송됩니다.

### admin 채널

| 이벤트 키 | 트리거 | 빌더 위치 |
|---|---|---|
| `signup_pending` | 신규 가입 신청이 접수되었을 때 (승인 대기) | `src/utils/webhook/events/signup.ts` |
| `signup_rejected` | 관리자가 가입 신청을 거부했을 때 | `src/utils/webhook/events/signup.ts` |
| `ticket_create` | 사용자가 새 티켓을 등록했을 때 | `src/utils/webhook/events/ticket.ts` |
| `ticket_status` | 티켓 상태(open/closed 등) 가 바뀌었을 때 | `src/utils/webhook/events/ticket.ts` |
| `user_ban` | 사용자 차단 / 차단 해제 | `src/utils/webhook/events/user.ts` |
| `user_role_change` | 사용자 역할 변경 (예: `user → admin`) | `src/utils/webhook/events/user.ts` |
| `super_admin_action` | 다른 admin 이벤트로 잡히지 않는 super_admin 행위 (전역 설정 변경 등) | `src/utils/webhook/events/superAdmin.ts` |

### community 채널

| 이벤트 키 | 트리거 | 빌더 위치 |
|---|---|---|
| `user_joined` | 신규 사용자가 가입을 완료했을 때 (open 정책 즉시 가입 / approval 정책 승인 직후) | `src/utils/webhook/events/signup.ts` |
| `discussion_create` | 문서에 새 토론이 열렸을 때 (잠금 페이지 / R2 전용 네임스페이스 제외) | `src/utils/webhook/events/discussion.ts` |
| `announcement_publish` | `settings.announce_post` 가 새 게시물로 변경되었을 때 (동일 게시물의 메타 갱신은 제외) | `src/utils/webhook/events/blog.ts` |

> 신규 토론 알림은 잠금 페이지(`is_locked`) 와 R2 전용 네임스페이스(`isR2OnlyNamespace`) 에서는 호출부에서 발송이 차단됩니다.
> 공지 알림은 동일 `postId` + 동일 `title` 인 단순 메타 갱신(no-op) 일 때 호출부에서 차단됩니다.

---

## Discord 웹훅 URL 발급

각 채널마다 Discord 측에서 채널 단위로 웹훅 URL 을 따로 만들어야 합니다.

1. Discord 에서 알림을 받을 **서버** 를 선택.
2. 운영자 알림용 텍스트 채널(예: `#wiki-admin`) 을 우클릭 → **채널 편집** → 좌측 **연동** → **웹훅 보기** → **새 웹훅** 클릭.
3. 이름은 자유롭게 (예: `Wiki Admin`), 발송 시 표시 이름은 `WIKI_NAME` 으로 덮어쓰기 됩니다.
4. **웹훅 URL 복사** 버튼으로 URL 을 확보 → 이 값이 `DISCORD_ADMIN_WEBHOOK_URL` 입니다.
5. 커뮤니티 알림용 채널(예: `#wiki-feed`) 에서도 같은 절차로 새 웹훅을 만들어 URL 을 복사 → 이 값이 `DISCORD_COMMUNITY_WEBHOOK_URL` 입니다.

> 한 채널에 두 종류 알림을 모두 보내고 싶다면 같은 URL 을 두 변수에 똑같이 등록해도 동작합니다. 다만 화이트리스트는 채널별로 독립이므로 양쪽 모두 적절히 채워야 합니다.
> 웹훅 URL 자체에 인증 토큰이 포함되어 있으므로 절대 공개 저장소에 커밋하지 말고 반드시 **Secret** 으로 등록하세요.

---

## Cloudflare 에 등록

웹훅 설정값의 등록 위치는 두 곳입니다.

- **URL 두 개 (`DISCORD_ADMIN_WEBHOOK_URL`, `DISCORD_COMMUNITY_WEBHOOK_URL`)**: Cloudflare 대시보드의 **Secret** (또는 `wrangler secret put` CLI). 토큰 포함이므로 절대 평문 변수로 두면 안 됩니다.
- **이벤트 화이트리스트 두 개 (`DISCORD_ADMIN_EVENTS`, `DISCORD_COMMUNITY_EVENTS`)**: `wrangler.toml` 의 `[vars]` 섹션

### URL — Secret 등록

`wrangler` CLI 로:
대시보드에서

[Cloudflare 대시보드](https://dash.cloudflare.com/) 접속
Workers 설정 → 변수 및 암호 경로로 접속, URL 두개를 **비밀** 변수로 등록하고 배포를 클릭합니다.