웹훅은 누군가 캠페인에 참여하거나 경품에 당첨되는 등 어떤 일이 일어나는 순간 지정한 URL로 데이터를 보냅니다. 데이터를 받는 시스템은 개발자가 설정합니다.
웹훅은 웹훅 및 API가 포함된 요금제(베이직 이상)에 포함됩니다.
캠페인 웹훅과 계정 웹훅
- 캠페인 웹훅은 캠페인 편집기에서 설정하며 해당 캠페인에서만 실행됩니다. “리드가 캠페인에 참여할 때마다”와 “리드가 경품에 당첨될 때” 이벤트가 있으며, 옵션이 가장 많습니다.
- 계정 웹훅은 설정 > 웹훅에서 설정합니다. “새 리드가 생성될 때” 이벤트가 있으며, 어느 캠페인에서 왔든 사람이 리드에 처음 추가될 때 한 사람당 한 번 실행됩니다.
캠페인에 웹훅 추가하기
- 편집기에서 캠페인을 열고 연결 > 웹훅으로 이동합니다.
- 웹훅 추가를 클릭합니다.
- 페이로드 URL을 입력합니다. https로 시작해야 합니다: “전송되는 데이터의 보안을 위해 HTTPS를 통한 웹훅만 지원합니다.”
- 콘텐츠 유형을 선택합니다: application/json 또는 application/x-www-form-urlencoded.
- 메서드를 선택합니다. 양식은 URL에 데이터를 담아 보내는 GET으로 시작합니다. 대부분의 시스템이 기대하는 방식대로 본문에 담아 보내려면 POST를 선택하세요.
- 인증(POST 전용)에서 URL에 사용자 이름과 비밀번호가 필요하면 Basic Auth를 선택하고 사용자 이름과 비밀번호를 입력합니다. 그렇지 않으면 없음으로 둡니다.
- 요청에 서명하려면 시크릿을 입력합니다(권장). 아래의 “서명 확인하기”를 참고하세요.
- 시스템의 응답 내용을 보려면 응답 본문 기록을 켭니다. “디버깅을 위해 응답 본문을 저장합니다.”
- 활성을 켜 둡니다. “웹훅이 활성 상태일 때만 이벤트를 전송합니다.”
- 이벤트를 선택합니다: “리드가 캠페인에 참여할 때마다” 또는 “리드가 경품에 당첨될 때”.
- 필드를 직접 정하려면 맞춤 페이로드를 켭니다(아래 참고).
- 웹훅 추가를 클릭합니다. “웹훅이 추가되었습니다”라는 메시지가 표시됩니다.
웹훅 패널에는 캠페인의 웹훅이 활성 또는 비활성 상태와 함께 표시되며, 최근 요청이 실패했다면 마지막 전송 실패도 표시됩니다. 작업에서 웹훅을 편집, 전송 내역 보기, 삭제할 수 있습니다. 웹훅을 편집할 때 기존 시크릿을 유지하려면 시크릿을 비워 두세요.
계정 웹훅 추가하기
- 설정 > 웹훅(개발자 아래)으로 이동합니다. 웹훅은 내 웹훅(리드 목록이 여러 개라면 각 리드 목록 이름 아래)에 나열됩니다.
- 더하기 표시가 있는 카드를 클릭해 웹훅을 추가합니다. 웹훅 추가 대화 상자에 “선택한 이벤트가 발생할 때마다 외부 URL로 요청을 보냅니다.”라고 표시됩니다.
- 위와 같이 페이로드 URL, 콘텐츠 유형(“웹훅의 콘텐츠 유형을 선택하세요”), 메서드, 시크릿을 입력합니다.
- **어떤 이벤트에서 웹훅을 실행할까요?**에서 “새 리드가 생성될 때”를 선택합니다.
- 필드를 직접 정하려면 “네, 맞춤 페이로드를 지정하겠습니다(고급 사용자 전용)”에 체크합니다.
- 필요하면 응답 본문 기록(“이 웹훅은 응답 본문을 기록합니다”)에 체크하고, 활성(“이 훅이 실행되면 이벤트 세부 정보를 전송합니다”)은 체크된 상태로 둡니다.
- 웹훅 추가를 클릭합니다.
웹훅을 클릭하면 변경(변경 사항 저장), 새 시크릿 설정, 전송 내역 표시, 웹훅 삭제(“이 작업은 되돌릴 수 없습니다!”)를 할 수 있습니다.
전송되는 데이터
기본적으로 본문에는 event(이벤트 이름: lead_created_on_campaign, new_campaign_winner, lead_created)와 data 객체가 포함됩니다.
campaign: 캠페인의id와name(캠페인 웹훅)lead: 필드 키(예:first_name)별 리드의 양식 필드와id,phone_number,created_atlead.permissions: 동의 체크박스마다 수락 여부, 문구, 날짜, IP 주소(캠페인 웹훅)participant: 유입된channel과 참여 시각(캠페인 웹훅)quiz: 이름이 지정된 퀴즈 질문의 답변. “Simple”로 시작하는 읽기 쉬운 이름으로도 포함됩니다prize: 경품의id,name,value,coupon_code와 당첨 시각(당첨자 웹훅)
빈 값과 수락되지 않은 동의 항목은 제외됩니다. GET 메서드에서는 같은 데이터가 URL의 쿼리 매개변수로 전송됩니다.
맞춤 페이로드
맞춤 페이로드를 켜면 선택한 필드만 전송되며 event 래퍼가 없습니다.
- 데이터 매핑에서 매핑 추가를 클릭합니다.
- 시스템이 기대하는 필드 이름을 입력합니다. 영문자, 숫자, 하이픈, 밑줄을 사용하세요.
- 보낼 Scratcher 필드(“그룹 → 필드”)를 선택하거나 사용자 지정 값을 선택하고 고정 값을 입력합니다.
- 필드마다 반복합니다. 휴지통(제거 또는 데이터 매핑 제거)으로 삭제할 수 있습니다.
서명 확인하기
시크릿을 설정하면 모든 요청에 X-Hub-Signature 헤더가 포함됩니다. 값은 sha1= 뒤에 시크릿을 키로 사용해 JSON 인코딩된 페이로드(위에서 설명한 본문)의 HMAC-SHA1 해시를 붙인 것입니다. 수신 측에서 같은 값을 계산해 비교하면 요청이 Scratcher에서 왔는지 확인할 수 있습니다.
전송과 재시도
- URL이 응답하지 않거나 오류(상태 코드 400 이상)를 반환하면 Scratcher는 5초 후와 1분 후, 두 번 더 시도합니다.
- 리디렉션은 따라가지 않으므로 최종 URL을 사용하세요.
- 전송 내역(캠페인에서는 전송 내역 보기, 계정 웹훅에서는 전송 내역 표시)을 열면 각 요청과 응답을 볼 수 있습니다. 각 전송 내역에는 ID, 요청, 상태 코드가 포함된 응답(응답을 기록하는 경우 응답 본문도)이 표시됩니다. 페이로드를 복사하려면 복사를 사용하세요.
- 문제만 보려면 실패한 전송만 표시를 켜세요. 상단에 “최근 60일간 실패한 전송”이 표시됩니다.
- 전송을 다시 보내려면 재시도를 클릭하세요: “웹훅을 다시 보내는 중입니다.”
- “웹훅 전송 로그는 60일 동안 보관됩니다.”
문제 해결
- “... 필드는 HTTPS를 사용해야 합니다.”: 페이로드 URL이 http로 시작합니다. https를 사용하세요.
- 모든 전송이 응답 없이 실패하는 경우: 로컬 주소나 내부 주소처럼 인터넷에서 접근할 수 없는 URL입니다. 공개 URL을 사용하세요.
- 시스템이 데이터를 받지 못하는 경우: 메서드가 GET이라 데이터가 URL에 담겨 있습니다. POST로 바꾸세요.
- 시스템이 기대하는 필드가 없는 경우: 값이 비어 있었거나 동의가 수락되지 않은 것입니다. 시스템에서 누락된 필드를 빈 값으로 처리하도록 하세요.