📤 아웃바운드 웹훅: 우리 시스템으로 사건 보내기
거래처가 오디언스에 들어오거나 빠질 때, 승인한 메시지가 나갔을 때 그 사실을 우리 회사의 다른 시스템(사내 앱 · 데이터 창고 · 메신저 봇 등)으로 보냅니다.
메뉴 위치 · 계정 › 연동 › 「아웃바운드 웹훅」 탭(관리자)(/account/integrations?tab=outbound_webhook)
1. 보내는 사건
| 화면 이름 | 사건 종류 | 언제 |
|---|---|---|
| 오디언스 진입 | segment.enter | 거래처가 거래처 오디언스에 새로 들어온 날 |
| 오디언스 이탈 | segment.exit | 거래처가 거래처 오디언스에서 빠진 날 |
| 승인 발송 완료 | message.sent | 담당자가 승인한 메시지가 나갔을 때 |
사건에는 식별자와 상태만 포함합니다. 메일 주소 · 전화번호 · 메시지 본문은 포함하지 않습니다.
2. 웹훅 만들기
- 「새 웹훅」에 이름과 받을 주소를 입력하고, 받을 사건을 하나 이상 선택한 뒤 「만들기」를 누릅니다.
- 서명 비밀은 이때만 표시됩니다. 복사해 두세요. 「닫기」를 누르거나 화면을 떠나면 다시 볼 수 없습니다.
- 목록의 「켜짐 · 꺼짐」 표시를 눌러 발송 여부를 정하고, 「최근 전달」에서 전달 결과를 확인합니다.
받는 주소는 https(443 포트)만 사용할 수 있습니다. 사내망 주소로는 보내지 않고 실패로 기록하며, 리다이렉트는 따라가지 않으므로 3xx 응답도 실패로 처리합니다.

3. 서명 확인(받는 쪽 개발자용)
요청 머리글 X-Sufly-Signature 의 값은 t=<초>,v1=<서명> 형식입니다.
t와 본문을 점(.)으로 연결한 문자열을 만듭니다.- 서명 비밀로 HMAC-SHA256 을 계산합니다.
- 결과가
v1과 같은지 확인합니다.t가 너무 오래된 요청은 폐기해 재전송을 차단합니다.
4. 실패하면
받는 쪽이 응답하지 않거나 실패하면 1분 · 5분 · 30분 · 2시간 · 12시간 뒤에 다시 보냅니다(12시간까지 다섯 번. 전달 작업이 5분마다 실행되므로 실제 시각은 몇 분 늦을 수 있습니다). 그래도 실패하면 「실패」로 기록되고, 사람이 직접 확인해야 합니다.
자주 묻는 질문
고객사(거래처)에게 웹훅이 가나요?
아닙니다. 우리 회사가 등록한 주소로만 전송됩니다.
받는 쪽 서버가 사내망에 있습니다.
사내망 주소로는 보내지 않습니다. 인터넷에서 https 로 받을 수 있는 주소가 필요합니다.
같은 사건이 두 번 올 수 있나요?
다시 보내는 과정에서 같은 전달이 한 번 더 도착할 수 있습니다. 같은 전달은 요청 머리글 X-Sufly-Delivery 값이 같으므로, 받는 쪽에서 이 값으로 중복된 요청을 제외하면 됩니다. 본문은 event · occurredAt · data 로 구성됩니다.
📎 함께 보기: 승인할 메시지와 채널 · API 키와 웹훅 인입