웹훅 개요

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

Inbound 웹훅과 혼동 주의

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

사용 흐름

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

관리 방법

웹훅은 두 경로로 등록하고 관리할 수 있습니다. 어느 경로로 만들어도 페이로드·서명·전달 규약은 같습니다.

• 대시보드: 채팅 설정 → 연동 / 개발 → Webhook 설정에서 관리합니다. 단계는 웹훅 설정을 참고하세요.
• PAT API(/api/public/v1/outbound-webhooks): 고객사 서버에서 웹훅을 코드로 등록하고 상태를 모니터링합니다. 조회에는 webhooks:read scope가, 변경에는 webhooks:write scope가 필요합니다. 엔드포인트 상세는 Outbound 웹훅 관리 API에 있습니다.

전달 보장

웹훅은 at-least-once로 전달됩니다. 전달 시도와 재전달 때문에 같은 이벤트가 두 번 이상 도착할 수 있으므로, 수신 측에서 멱등(idempotent) 처리를 하세요. 중복을 가려내는 방법은 전달에 있습니다.

전달에 실패한 이벤트는 이벤트 접수 시점부터 최대 약 24시간 동안 다시 전달합니다. 그 이후에는 폐기합니다. 웹훅이 도착하지 않으면 웹훅이 도착하지 않을 때를 확인하세요.