웹훅

고른 이벤트가 생기면 서명한 JSON 을 HTTPS 로 받을 엔드포인트를 만들고, 전송 기록을 보고 다시 보내는 화면입니다.

하는 일

“연동” 메뉴는 “웹훅”·“API 키”·“받는 주소”·“분석 연동” 탭으로 나뉘며, 메뉴를 열면 “웹훅” 탭이 먼저 열립니다. “웹훅 엔드포인트” 표에는 “주소”와 설명, 받는 “이벤트” 수, “상태”(“활성”·“꺼짐”·“실패로 비활성”과 꺼진 이유), “만든 사람”, “마지막 전송”이 나옵니다. 받을 수 있는 이벤트는 “리드 생성”, “피드백 접수”, “쿠폰 발급”, “위젯 게시”, “사이트 설치 감지”, “리드 수신 동의 확인”, “리드 수신 거부”입니다.

행을 누르면 엔드포인트 페이지가 열립니다. “엔드포인트” 영역에는 주소·이벤트·설명·상태, “연속 실패”, “꺼진 이유”, “실패 시작”, “만든 사람”, “만든 시각”, “서명 비밀 만든 시각”, “옛 비밀 유효”가 있고, 이어서 “전송 기록”과 받는 서버에 넣을 “서명 확인 방법” 코드가 있습니다.

웹훅은 요금제에 따라 쓸 수 있습니다. 조직의 요금제에 웹훅·API 기능이 없으면 “웹훅·API 는 Growth 요금제부터 쓸 수 있습니다” 안내와 “요금제 보기”가 나옵니다. 이때는 새로 만들거나 보낼 수 없고, 이미 만든 것은 보고 끄거나 지울 수 있습니다.

수신 동의 더블 옵트인에 따라 “리드 생성” 이벤트의 동의는 방문자가 확인하기 전까지 marketing 이 false, marketingStatus 가 pending 입니다. 방문자가 확인 메일로 동의를 확인하면 “리드 수신 동의 확인”, 수신 거부 링크로 철회하면 “리드 수신 거부” 이벤트를 받을 수 있습니다. 마케팅 메일 발송 목록은 이 두 이벤트로 맞추세요.

단계

1단계 · 새 엔드포인트 만들기
“새 엔드포인트”를 누르고 “주소 (URL)”를 넣습니다. “받을 이벤트”를 하나 이상 고르고(처음에는 “리드 생성”이 골라져 있습니다), 필요하면 “설명”을 씁니다. “엔드포인트 만들기”를 누르면 “현재 비밀번호”를 묻는 창이 뜨고, 입력한 뒤 “확인하고 저장”을 누릅니다.
2단계 · 서명 비밀 저장하기
“서명 비밀” 창에 비밀이 한 번만 보입니다. “서명 비밀 복사”로 복사해 받는 서버에 저장하고 “저장했습니다”를 누릅니다. 다른 방법으로 닫으려 하면 “저장하지 않고 닫을까요?”를 묻습니다. 창을 닫으면 그 엔드포인트의 페이지가 열립니다.
3단계 · 받는 서버에서 서명 확인하기
“서명 확인 방법”을 읽고 “확인 코드 복사”로 예시 코드를 가져갑니다. 요청마다 붙는 BzWidget-Signature 헤더를 서명 비밀로 확인하고, t 가 5분 안인지 보고, 같은 BzWidget-Event-Id 는 한 번만 처리합니다.
4단계 · 테스트 전송하기
엔드포인트 페이지에서 “테스트 이벤트”를 고르고 “테스트 전송”을 누릅니다. 결과는 “테스트 전송 결과:”와 상태로 알려 주며, “전송 기록”에 “테스트” 표시가 붙은 행이 생깁니다.
5단계 · 전송 기록 보고 다시 보내기
“전송 기록”에서 “전체”·“보내는 중”·“재시도 대기”·“성공”·“실패”로 거릅니다. “본문 보기”는 “전송 상세” 창에서 요청 헤더·본문, 응답, “시도 기록”을 보여 줍니다. 실패한 건은 “재전송”으로 다시 보냅니다.

버튼

새 엔드포인트: 새 엔드포인트 창을 엽니다. 요금제에 웹훅 기능이 있는 Owner·Admin 에게만 보입니다.
엔드포인트 만들기 · 저장: 입력한 주소와 이벤트로 엔드포인트를 만들거나 고친 값을 저장합니다. 만들 때와 주소·이벤트를 바꿀 때는 현재 비밀번호를 한 번 더 확인합니다. 설명만 바꿀 때는 묻지 않습니다.
고치기: “엔드포인트 고치기” 창을 열어 주소·이벤트·설명을 바꿉니다.
켜기 · 끄기: “끄기”는 확인 창을 거쳐 새 이벤트를 보내지 않고 예약된 재시도도 멈춥니다. 꺼진 엔드포인트에는 “켜기”가 보이며, 켜면 이어서 보내고 연속 실패 수를 0으로 되돌립니다.
비밀 교체: 확인 창과 현재 비밀번호 확인을 거쳐 새 서명 비밀을 만들어 한 번 보여 줍니다. 옛 비밀은 24시간 동안 함께 서명하므로 그 안에 받는 서버의 비밀을 바꾸세요.
삭제: 엔드포인트와 전송 기록을 지웁니다. 확인 창을 거치며 되돌릴 수 없습니다.
테스트 전송: 고른 “테스트 이벤트”의 예시 본문을 지금 한 번 보냅니다. 실패하면 성공이라 하지 않고 그 상태를 경고로 알려 줍니다.
본문 보기 · 재전송: “본문 보기”는 그 전송의 상세를 엽니다. “재전송”은 “보내는 중”이 아닌 전송을 다시 보내고 결과를 “다시 보냈습니다:”로 알려 줍니다.

권한

“연동” 메뉴는 Owner·Admin 만 열 수 있고, 엔드포인트를 만들고 고치고 지우는 것도 Owner·Admin 만 할 수 있습니다. Editor·Analyst 에게는 메뉴가 보이지 않으며, 주소를 직접 열면 “이 작업을 할 권한이 없습니다.”가 나옵니다.

요금제에 웹훅·API 기능이 없으면 “새 엔드포인트”, “고치기”, “켜기”, “비밀 교체”, “테스트 전송”, “재전송”이 보이지 않습니다. “끄기”와 “삭제”는 남아 있어 정리할 수 있습니다.

조직이 읽기 전용이면 만들기·고치기·켜기·비밀 교체·테스트 전송·재전송 버튼이 꺼지고 “조직이 읽기 전용이라 바꿀 수 없습니다.”가 보입니다. “끄기”와 “삭제”는 읽기 전용일 때도 쓸 수 있습니다.

자주 묻는 질문

주소를 넣었는데 받아 주지 않습니다.: https 로 시작하는 공개 주소만 쓸 수 있습니다. IP 주소, 내부·로컬 주소, 443 아닌 포트, 사용자 이름·비밀번호가 든 주소, # 이후 부분이 있는 주소는 받지 않으며, 주소는 2048자까지입니다. 이유는 “주소 (URL)” 칸 밑에 나옵니다. 같은 주소의 엔드포인트가 이미 있어도 만들 수 없습니다.
엔드포인트가 “실패로 비활성”이 되었습니다.: 실패한 전송은 1분·5분·30분·2시간·6시간·24시간 뒤 다시 보냅니다. 72시간 넘게 이어서 실패하고 연속 실패가 10번이 되면 엔드포인트를 끄고 Owner·Admin 에게 메일로 알립니다. 받는 서버를 고친 뒤 “테스트 전송”으로 확인하고 “켜기”를 누르세요.
서명 비밀을 잃어버렸습니다.: 비밀은 만들 때와 교체할 때 한 번만 보이며 다시 볼 수 없습니다. “비밀 교체”로 새 비밀을 받으세요. 옛 비밀은 24시간 동안 함께 서명합니다.
엔드포인트를 더 만들 수 없거나 테스트가 거절됩니다.: 엔드포인트는 조직당 10개까지 만들 수 있습니다. 테스트 전송과 재전송은 엔드포인트마다 1분에 10번까지이며, 넘으면 “직접 보내기(테스트·재전송)가 1분 한도를 넘었습니다. 잠시 뒤 다시 시도하세요.”가 나옵니다.
전송 기록은 얼마나 남고 무엇이 보이나요?: 전송 기록은 30일 동안 보관합니다. 본문은 4096바이트에서 자르고 개인정보 필드는 [redacted] 로 가립니다. 응답 본문에 보낸 개인정보가 들어 있으면 응답 본문을 저장하지 않습니다.