웹훅 개요

ZeroTalk는 워크스페이스에서 메시지·채널 이벤트가 발생하면 등록한 endpoint로 HTTP POST를 보냅니다 (Outbound Webhook). CRM 동기화, BI 적재, 외부 알림 연동 등에 활용할 수 있습니다.

Inbound 웹훅과 혼동 주의

이 문서의 Outbound 웹훅은 ZeroTalk가 내 서버로 이벤트를 내보내는 방향입니다. 반대로 카카오·네이버 등 외부 메신저 공급자가 ZeroTalk로 메시지를 전달하는 인바운드 웹훅 설정(inbound-webhook-configs)은 전혀 별개이며 조회 전용입니다 (엔드포인트 카탈로그 참고).

사용 흐름

1. 웹훅 설정에서 수신 URL과 구독할 이벤트를 등록하고 시크릿을 발급받습니다
2. 수신 endpoint에서 서명을 검증해 요청의 진위를 확인합니다
3. 이벤트 페이로드를 처리합니다

관리 방법

웹훅은 두 경로로 등록·관리할 수 있습니다. 어느 경로로 만들든 페이로드·서명·전달 규약은 동일합니다.

• 대시보드 UI — 채팅 설정 → 연동 / 개발 → Webhook 설정. 단계는 웹훅 설정을 참고하세요.
• PAT API (/api/public/v1/outbound-webhooks) — BFF·서버에서 웹훅을 프로그래밍 방식으로 프로비저닝하고 상태를 모니터링합니다. scope는 조회 webhooks:read, 변경 webhooks:write. 엔드포인트 상세는 Outbound 웹훅 관리 API에 있습니다.

전달 보장

웹훅은 at-least-once로 전달됩니다 — 전달 시도와 재전달 때문에 같은 이벤트가 두 번 이상 도착할 수 있습니다. 단, 재전달은 이벤트 접수 시점부터 최대 약 24시간까지만 시도되며 그 이후에는 폐기됩니다. 수신 측에서 멱등(idempotent) 처리를 권장합니다. 자세한 내용은 전달을 참고하세요.