웹훅 설정
웹훅을 등록하면 새 메시지·채널 상태 변경 등의 이벤트를 등록한 URL로 수신할 수 있습니다. 등록·관리는 대시보드 UI와 PAT API 두 경로로 할 수 있으며(아래 API로 관리하기), 어느 쪽으로 만들든 동작은 같습니다.
대시보드에서 등록
API로 관리하기
대시보드 대신 PAT(Personal Access Token) 로도 웹훅을 등록·운영할 수 있습니다. BFF나 백엔드에서 워크스페이스별 웹훅을 자동 프로비저닝하거나 상태를 모니터링할 때 사용합니다.
| 작업 | 엔드포인트 |
|---|---|
| 생성 (시크릿 1회 반환) | POST /api/public/v1/outbound-webhooks |
| 시크릿 회전 (시크릿 1회 반환) | POST …/{id}/regenerate-secret |
| 활성 / 비활성 전환 | POST …/{id}/toggle |
| 전달 로그 조회 | GET …/{id}/delivery-logs |
- Scope: 조회
webhooks:read, 변경webhooks:write. - 서명 시크릿은 생성·회전 응답에서만 평문으로 1회 노출됩니다(목록·조회는 미반환). 받은 즉시 서버에 저장하세요.
- 요청·응답 예시와 전체 8개 엔드포인트(목록·단건 조회·수정·삭제 포함)는 Outbound 웹훅 관리 API를 참고하세요.
URL 제약
- HTTPS만 허용됩니다
- IP 주소를 직접 넣을 수 없습니다 (도메인만 허용)
- 사설·예약 대역(
10.x,172.16~31.x,192.168.x,127.x,169.254.x,100.64.x등)과 메타데이터 호스트(169.254.169.254,metadata.google.internal)는 차단됩니다 - 송신 시점에 도메인이 해석되는 IP도 재검증합니다 (DNS rebinding 방지)
- 최대 2048자
시크릿
등록 시 64자 hex 문자열 시크릿이 자동 발급되며, 발급 화면에서 한 번만 표시됩니다(복사해 두세요). 이 시크릿으로 서명을 검증합니다. 분실 시 대시보드의 Regenerate Secret(PAT는 POST /outbound-webhooks/{id}/regenerate-secret)으로 회전할 수 있습니다(즉시 적용, grace 기간 없음).
상태
| 상태 | 의미 |
|---|---|
active | 정상 송신 (기본값) |
inactive | 일시 중지 (대시보드 토글 또는 PAT toggle) |
error | 연속 실패로 자동 비활성화됨 — 전환 시 워크스페이스 관리자에게 이메일·대시보드 알림 발송 (전달 참고) |
대시보드 토글(PAT는 POST /outbound-webhooks/{id}/toggle)로 active ↔ inactive를 전환하고, 더 이상 쓰지 않는 웹훅은 삭제할 수 있습니다.