suflyCRM

개발자 문서 · 웹훅·연동 · 최종 수정 2026-08-16

🪝 웹훅과 연동

외부 시스템에서 서플라이 CRM으로 이벤트를 보내는 수신 웹훅과, 앱에서 설정하는 협업 도구 연동의 개요입니다.

1️⃣ CS 문의 웹훅: POST /api/webhooks/cs-support

외부 고객지원 위젯·폼에서 받은 문의를 Support 티켓으로 접수합니다.

항목내용
인증API 키(전용 키). 키 없음/오류 시 거부
멱등source + externalId 조합으로 중복 접수 방지 - 같은 문의를 재전송해도 티켓은 1개
처리티켓 생성 → 접수 확인 자동 회신 → 고객사 자동 연결 시도 → 담당자 선반영
첨부첨부 파일 업로드를 지원
응답3초 내 200 후 배경 처리(웹훅 표준 - 응답을 오래 붙잡지 않습니다)

⚠️ 연동 전 출처 등록이 필요합니다. 위젯 문의가 올바른 조직으로 접수되려면 요청 출처(도메인)를 사전에 등록해야 합니다. 신규 위젯을 연결하기 전에 서플라이 CRM 온보딩 담당자와 인입 출처 등록을 먼저 진행하세요.

2️⃣ 메일 전송 이벤트 (참고)

서플라이 CRM에서 발송한 메일의 오픈·클릭·반송 성과는 플랫폼이 자동으로 집계합니다. 고객사 개발자가 별도로 구현할 것은 없습니다.

3️⃣ 협업 도구 연동 (Asana 등)

연동 설정은 앱에서 합니다(테넌트 관리 > 연동). 개발자가 코드로 붙이는 대상이 아니라, 관리자가 화면에서 연결하는 기능입니다.

도구방향상태개발자가 할 일
AsanaAsana → Support (태스크→티켓)라이브없음 - 앱에서 프로젝트 연결만. 연동 시점 이후 태스크만 인입(소급 없음)

자세한 동작은 Asana 프로젝트 연동 가이드를 참고하세요.

4️⃣ 웹훅 구현 체크리스트 (보내는 쪽)

  • 각 이벤트에 고유 `externalId`를 부여했는가 - 멱등 보장, 재전송 안전.
  • API 키를 서버 측에만 두었는가 - 브라우저·앱 번들에 키를 넣지 말 것.
  • 5xx·429에 지수 백오프 재시도를 넣었는가.
  • 4xx(검증 실패)는 재시도하지 않고 요청을 고치는가.
  • 응답 본문의 success·details를 로깅해 실패를 추적하는가.

5️⃣ 밖으로 보내는 웹훅 (아웃바운드)

관리자가 연동 › 「아웃바운드 웹훅」 탭에서 받을 주소를 등록하면, 사건이 생길 때 그 주소로 보냅니다. 사건은 오디언스 진입 · 오디언스 이탈 · 승인 발송 완료 세 가지입니다.

항목내용
받는 주소https(443 포트)만. 사내망 주소로는 보내지 않고, 리다이렉트는 따라가지 않습니다
본문{ event, occurredAt, data }. 메일 주소 · 전화번호 · 메시지 본문은 싣지 않습니다
서명X-Sufly-Signature: t=<초>,v1=<HMAC-SHA256(t.본문)>
전달 번호X-Sufly-Delivery
재시도1분 · 5분 · 30분 · 2시간 · 12시간 간격으로 다섯 번

자세한 설정은 아웃바운드 웹훅을 참고하세요.

6️⃣ 주문 받기: POST /api/webhooks/orders

쇼핑몰 · 자체 주문 시스템의 주문을 CRM 매출 기록으로 가져올 수 있습니다. 「주문 보내기 · 서버끼리만」(order:write) 권한이 있는 API 키로 보냅니다. 같은 주문을 다시 보내도 한 건으로 셉니다. 동작은 API 키와 웹훅 인입의 「외부 주문 받기」를 참고하세요.

🚀 다음 단계

👉 인증 헤더와 요청 스키마는 인증과 리드 인입 API에서 확인하세요.