---
title: "웹훅으로 시스템에 데이터 보내기"
description: "누군가 가입하거나, 참여하거나, 당첨될 때 내 URL로 요청을 받으세요. 서명된 페이로드, 기본 인증, 맞춤 페이로드, 모든 전송 내역 로그를 지원합니다."
url: https://scratcher.io/ko/help/developers/webhooks
language: ko
---

1. [도움말 센터](https://scratcher.io/ko/help)
2. [API, 웹훅, MCP](https://scratcher.io/ko/help/developers)
3. 웹훅으로 시스템에 데이터 보내기

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

누군가 가입하거나, 참여하거나, 당첨될 때 내 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**로 바꾸세요.
- 시스템이 기대하는 필드가 없는 경우: 값이 비어 있었거나 동의가 수락되지 않은 것입니다. 시스템에서 누락된 필드를 빈 값으로 처리하도록 하세요.

API, 웹훅, MCP

- [REST API 시작하기](https://scratcher.io/ko/help/developers/rest-api)
- [웹훅으로 시스템에 데이터 보내기](https://scratcher.io/ko/help/developers/webhooks)
- [내 AI 도구를 위한 Scratcher MCP](https://scratcher.io/ko/help/developers/mcp)

더 알아보기

## 관련 글

- [REST API 시작하기](https://scratcher.io/ko/help/developers/rest-api): 올바른 범위의 개인 액세스 토큰을 만들거나 OAuth 앱을 등록하고, 자체 시스템에서 캠페인, 리드, 목록을 읽으세요.
- [전송 상태 확인 및 리드 재전송](https://scratcher.io/ko/help/integrations/delivery-status): 어떤 리드가 도구로 전송되었는지 확인하고, 오류 메시지를 이해하고, 문제를 해결한 뒤 다시 보내세요.
- [Zapier로 8,000개 이상의 앱 연결하기](https://scratcher.io/ko/help/integrations/zapier): Zapier를 사용해 Scratcher의 새 가입자를 Google Sheets, Slack, CRM 등 수천 개의 앱으로 보내세요.

도움이 필요하신가요?

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

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

- **[채팅 문의](https://platform.scratcher.io/ko/login)**

    로그인한 뒤 오른쪽 아래의 채팅 버튼을 클릭하세요. Rex가 바로 답하고, 팀과도 클릭 한 번으로 연결됩니다.
- **[미팅 예약](https://scratcher.io/ko/book-a-meeting)**

    팀과의 무료 30분 화상 통화: 둘러보기, 캠페인 아이디어, 설정 지원.
- **[이메일 문의](mailto:contact@scratcher.io)**

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