🪝 웹훅과 연동
외부 시스템에서 sufly®로 이벤트를 보내는 수신 웹훅과, 앱에서 설정하는 협업 도구 연동의 개요입니다.
1️⃣ CS 문의 웹훅 - POST /api/webhooks/cs-support
외부 고객지원 위젯·폼에서 받은 문의를 Support 티켓으로 접수합니다.
| 항목 | 내용 |
|---|---|
| 인증 | API 키(전용 키). 키 없음/오류 시 거부 |
| 멱등 | source + externalId 조합으로 중복 접수 방지 - 같은 문의를 재전송해도 티켓은 1개 |
| 처리 | 티켓 생성 → 접수 확인 자동 회신 → 고객사 자동 연결 시도 → 담당자 선반영 |
| 첨부 | 첨부 파일 업로드를 지원 |
| 응답 | 3초 내 200 후 배경 처리(웹훅 표준 - 응답을 오래 붙잡지 않습니다) |
⚠️ 연동 전 출처 등록이 필요합니다. 위젯 문의가 올바른 조직으로 접수되려면 요청 출처(도메인)를 사전에 등록해야 합니다. 신규 위젯을 연결하기 전에 sufly® 온보딩 담당자와 인입 출처 등록을 먼저 진행하세요.
2️⃣ 메일 전송 이벤트 (참고)
sufly®에서 발송한 메일의 오픈·클릭·반송 성과는 플랫폼이 자동으로 집계합니다. 고객사 개발자가 별도로 구현할 것은 없습니다.
3️⃣ 협업 도구 연동 (Asana 등)
연동 설정은 앱에서 합니다(테넌트 관리 > 연동). 개발자가 코드로 붙이는 대상이 아니라, 관리자가 화면에서 연결하는 기능입니다.
| 도구 | 방향 | 상태 | 개발자가 할 일 |
|---|---|---|---|
| Asana | Asana → Support (태스크→티켓) | 라이브 | 없음 - 앱에서 프로젝트 연결만. 연동 시점 이후 태스크만 인입(소급 없음) |
자세한 동작은 Asana 프로젝트 연동 가이드를 참고하세요.
4️⃣ 웹훅 구현 체크리스트 (보내는 쪽)
- 각 이벤트에 고유 `externalId`를 부여했는가 - 멱등 보장, 재전송 안전.
- API 키를 서버 측에만 두었는가 - 브라우저·앱 번들에 키를 넣지 말 것.
5xx·429에 지수 백오프 재시도를 넣었는가.4xx(검증 실패)는 재시도하지 않고 요청을 고치는가.- 응답 본문의
success·details를 로깅해 실패를 추적하는가.
🚀 다음 단계
👉 인증 헤더와 요청 스키마는 인증과 리드 인입 API에서 확인하세요.