웹훅 설정

웹훅을 등록하면 새 메시지나 채널 상태 변경 같은 이벤트를 등록한 URL로 받을 수 있습니다. 대시보드와 PAT API 중 편한 경로로 등록하고 관리하세요(PAT API는 API로 관리하기를 참고하세요). 어느 쪽으로 만들어도 동작은 같습니다.

대시보드에서 등록

1. 대시보드 → 채팅 설정 → 연동 / 개발 → Webhook 설정으로 이동합니다.
2. + Webhook 추가를 클릭합니다.
3. 이름, URL, 받을 구독 이벤트를 입력합니다. 구독 이벤트는 이벤트 목록에서 고르며, 아무것도 고르지 않으면 모든 이벤트를 받습니다.
4. 저장하면 나타나는 Webhook Secret 창에서 시크릿을 복사해 수신 서버에 저장합니다. 이 시크릿은 서명 검증에 사용합니다.

API로 관리하기

대시보드 대신 PAT(Personal Access Token) 로도 웹훅을 등록하고 운영할 수 있습니다. 워크스페이스별 웹훅을 자동으로 만들거나 상태를 모니터링해야 할 때 사용하세요.

작업	엔드포인트
생성 (시크릿 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 제약

웹훅 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)는 차단됩니다.
• ZeroTalk는 전송할 때마다 도메인이 가리키는 IP를 다시 검사합니다(DNS rebinding 방지). 등록할 때 통과한 도메인이라도 나중에 사설 IP를 가리키면 전송이 실패합니다.
• 최대 2048자입니다.

시크릿

웹훅을 등록하면 64자 hex 문자열 시크릿이 자동으로 발급됩니다. 발급 화면에는 한 번만 표시되므로 복사해 두세요. 이 시크릿으로 서명을 검증합니다.

시크릿을 잃어버렸다면 대시보드의 키 재생성(PAT는 POST /outbound-webhooks/{id}/regenerate-secret)으로 새로 발급받으세요. 재생성하면 기존 시크릿이 즉시 무효가 되고 유예 기간은 없습니다. 새 시크릿 적용 절차는 시크릿 회전을 참고하세요.

상태

상태	대시보드 표시	의미
active	활성	정상 송신합니다. 기본값입니다.
inactive	비활성	사람이 일시 중지한 상태입니다. 대시보드 토글 또는 PAT toggle로 바꿉니다.
error	오류	연속 실패로 자동 비활성화된 상태입니다. 전환되면 워크스페이스 관리자에게 이메일과 대시보드 알림을 보냅니다. 복구 조건은 전달을 참고하세요.

대시보드의 토글(PAT는 POST /outbound-webhooks/{id}/toggle)로 active와 inactive를 전환할 수 있습니다. 더 이상 쓰지 않는 웹훅은 삭제하세요.