본문으로 건너뛰기
AI 어시스턴트 Rex: 번거로운 일은 맡기고, 아이디어는 여러분의 것으로 👉 Rex 만나기

웹훅으로 시스템에 데이터 보내기

누군가 가입하거나, 참여하거나, 당첨될 때 내 URL로 요청을 받으세요. 서명된 페이로드, 기본 인증, 맞춤 페이로드, 모든 전송 내역 로그를 지원합니다.

웹훅은 누군가 캠페인에 참여하거나 경품에 당첨되는 등 어떤 일이 일어나는 순간 지정한 URL로 데이터를 보냅니다. 데이터를 받는 시스템은 개발자가 설정합니다.

웹훅은 웹훅 및 API가 포함된 요금제(베이직 이상)에 포함됩니다.

캠페인 웹훅과 계정 웹훅

  • 캠페인 웹훅은 캠페인 편집기에서 설정하며 해당 캠페인에서만 실행됩니다. “리드가 캠페인에 참여할 때마다”와 “리드가 경품에 당첨될 때” 이벤트가 있으며, 옵션이 가장 많습니다.
  • 계정 웹훅은 설정 > 웹훅에서 설정합니다. “새 리드가 생성될 때” 이벤트가 있으며, 어느 캠페인에서 왔든 사람이 리드에 처음 추가될 때 한 사람당 한 번 실행됩니다.

캠페인에 웹훅 추가하기

  1. 편집기에서 캠페인을 열고 연결 > 웹훅으로 이동합니다.
  2. 웹훅 추가를 클릭합니다.
  3. 페이로드 URL을 입력합니다. https로 시작해야 합니다: “전송되는 데이터의 보안을 위해 HTTPS를 통한 웹훅만 지원합니다.”
  4. 콘텐츠 유형을 선택합니다: application/json 또는 application/x-www-form-urlencoded.
  5. 메서드를 선택합니다. 양식은 URL에 데이터를 담아 보내는 GET으로 시작합니다. 대부분의 시스템이 기대하는 방식대로 본문에 담아 보내려면 POST를 선택하세요.
  6. 인증(POST 전용)에서 URL에 사용자 이름과 비밀번호가 필요하면 Basic Auth를 선택하고 사용자 이름과 비밀번호를 입력합니다. 그렇지 않으면 없음으로 둡니다.
  7. 요청에 서명하려면 시크릿을 입력합니다(권장). 아래의 “서명 확인하기”를 참고하세요.
  8. 시스템의 응답 내용을 보려면 응답 본문 기록을 켭니다. “디버깅을 위해 응답 본문을 저장합니다.”
  9. 활성을 켜 둡니다. “웹훅이 활성 상태일 때만 이벤트를 전송합니다.”
  10. 이벤트를 선택합니다: “리드가 캠페인에 참여할 때마다” 또는 “리드가 경품에 당첨될 때”.
  11. 필드를 직접 정하려면 맞춤 페이로드를 켭니다(아래 참고).
  12. 웹훅 추가를 클릭합니다. “웹훅이 추가되었습니다”라는 메시지가 표시됩니다.

웹훅 패널에는 캠페인의 웹훅이 활성 또는 비활성 상태와 함께 표시되며, 최근 요청이 실패했다면 마지막 전송 실패도 표시됩니다. 작업에서 웹훅을 편집, 전송 내역 보기, 삭제할 수 있습니다. 웹훅을 편집할 때 기존 시크릿을 유지하려면 시크릿을 비워 두세요.

계정 웹훅 추가하기

  1. 설정 > 웹훅(개발자 아래)으로 이동합니다. 웹훅은 내 웹훅(리드 목록이 여러 개라면 각 리드 목록 이름 아래)에 나열됩니다.
  2. 더하기 표시가 있는 카드를 클릭해 웹훅을 추가합니다. 웹훅 추가 대화 상자에 “선택한 이벤트가 발생할 때마다 외부 URL로 요청을 보냅니다.”라고 표시됩니다.
  3. 위와 같이 페이로드 URL, 콘텐츠 유형(“웹훅의 콘텐츠 유형을 선택하세요”), 메서드, 시크릿을 입력합니다.
  4. **어떤 이벤트에서 웹훅을 실행할까요?**에서 “새 리드가 생성될 때”를 선택합니다.
  5. 필드를 직접 정하려면 “네, 맞춤 페이로드를 지정하겠습니다(고급 사용자 전용)”에 체크합니다.
  6. 필요하면 응답 본문 기록(“이 웹훅은 응답 본문을 기록합니다”)에 체크하고, 활성(“이 훅이 실행되면 이벤트 세부 정보를 전송합니다”)은 체크된 상태로 둡니다.
  7. 웹훅 추가를 클릭합니다.

웹훅을 클릭하면 변경(변경 사항 저장), 새 시크릿 설정, 전송 내역 표시, 웹훅 삭제(“이 작업은 되돌릴 수 없습니다!”)를 할 수 있습니다.

전송되는 데이터

기본적으로 본문에는 event(이벤트 이름: lead_created_on_campaign, new_campaign_winner, lead_created)와 data 객체가 포함됩니다.

  • campaign: 캠페인의 id와 name(캠페인 웹훅)
  • lead: 필드 키(예: first_name)별 리드의 양식 필드와 id, phone_number, created_at
  • lead.permissions: 동의 체크박스마다 수락 여부, 문구, 날짜, IP 주소(캠페인 웹훅)
  • participant: 유입된 channel과 참여 시각(캠페인 웹훅)
  • quiz: 이름이 지정된 퀴즈 질문의 답변. “Simple”로 시작하는 읽기 쉬운 이름으로도 포함됩니다
  • prize: 경품의 id, name, value, coupon_code와 당첨 시각(당첨자 웹훅)

빈 값과 수락되지 않은 동의 항목은 제외됩니다. GET 메서드에서는 같은 데이터가 URL의 쿼리 매개변수로 전송됩니다.

맞춤 페이로드

맞춤 페이로드를 켜면 선택한 필드만 전송되며 event 래퍼가 없습니다.

  1. 데이터 매핑에서 매핑 추가를 클릭합니다.
  2. 시스템이 기대하는 필드 이름을 입력합니다. 영문자, 숫자, 하이픈, 밑줄을 사용하세요.
  3. 보낼 Scratcher 필드(“그룹 → 필드”)를 선택하거나 사용자 지정 값을 선택하고 고정 값을 입력합니다.
  4. 필드마다 반복합니다. 휴지통(제거 또는 데이터 매핑 제거)으로 삭제할 수 있습니다.

서명 확인하기

시크릿을 설정하면 모든 요청에 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로 바꾸세요.
  • 시스템이 기대하는 필드가 없는 경우: 값이 비어 있었거나 동의가 수락되지 않은 것입니다. 시스템에서 누락된 필드를 빈 값으로 처리하도록 하세요.
도움이 필요하신가요?

아직 도움이 필요하신가요?

실제 담당자가 도와드립니다. 이미 Scratcher를 사용 중이라면 플랫폼 안의 채팅이 가장 빠릅니다.

  • 채팅 문의

    로그인한 뒤 오른쪽 아래의 채팅 버튼을 클릭하세요. Rex가 바로 답하고, 팀과도 클릭 한 번으로 연결됩니다.

  • 미팅 예약

    팀과의 무료 30분 화상 통화: 둘러보기, 캠페인 아이디어, 설정 지원.

  • 이메일 문의

    contact@scratcher.io로 연락 주시면 답변드리겠습니다.