인바운드 웹훅 통합

인바운드 웹훅을 사용하면 서드파티 서비스가 Pushwoosh로 직접 이벤트를 보낼 수 있습니다. 서드파티 서비스가 웹훅을 트리거하면 Pushwoosh는 요청을 인증하고 사용자를 식별한 다음, 구성한 매핑을 적용합니다. 즉, 사용자 프로필의 태그를 채우거나 Pushwoosh 이벤트를 발생시키거나 둘 다 수행합니다. 발생된 이벤트는 Journey를 시작하거나 진행시킬 수 있습니다.

인바운드 웹훅을 사용하여 자체 서버를 구축하거나 유지 관리할 필요 없이 CRM, 전자상거래 플랫폼 또는 분석 서비스와 같은 도구를 연결하세요.

들어오는 식별자가 기존 사용자와 일치하지 않는 경우, Pushwoosh는 요청을 삭제하는 대신 사용자를 생성할 수 있습니다. 수신 데이터 매핑에 설명된 자동 생성 확인란을 켜세요.

시작하기 전에

웹훅 설정을 열기 전에 다음을 준비하세요.

웹훅이 수행할 작업을 결정하세요. 웹훅은 최소한 하나의 태그, 하나의 이벤트 또는 둘 다를 매핑해야 합니다. 이벤트를 발생시키려면 프로젝트에서 기존 이벤트(예: CheckoutSuccess)를 선택하거나 들어오는 데이터로 채우고 싶은 속성을 사용하여 새로운 이벤트를 생성하세요. 태그는 기존 태그에 매핑하거나 웹훅을 설정하는 동안 즉시 생성할 수 있습니다.
서드파티 서비스가 웹훅을 보낼 수 있는지 확인하세요. 이 서비스는 새로운 주문이나 양식 제출과 같이 관심 있는 이벤트가 발생했을 때 외부 URL로 HTTP POST 요청을 보낼 수 있어야 합니다.
서드파티 서비스에서 샘플 JSON 페이로드를 받으세요. 이는 서비스가 각 이벤트마다 보내는 데이터의 작은 예시입니다. 페이로드 필드를 태그 및 이벤트 속성에 매핑하는 데 필요합니다.

웹훅 생성

웹훅 설정 열기

Pushwoosh 계정에서 설정 → 통합 → 인바운드 웹훅으로 이동하여 설정을 클릭합니다.

인바운드 웹훅 카드와 웹훅 구성을 열기 위한 설정 버튼이 있는 통합 페이지

웹훅 생성을 클릭하여 설정 화면을 엽니다. 왼쪽에는 샘플 페이로드 붙여넣기, 오른쪽에는 웹훅 설정이 있습니다.

왼쪽에 페이로드 편집기, 오른쪽에 빈 웹훅 설정 패널이 있는 빈 웹훅 생성 화면

나중에 목록에서 웹훅을 식별할 수 있도록 웹훅 이름을 입력하세요.

수신 데이터 매핑

샘플 페이로드 붙여넣기에 서드파티 서비스의 샘플 JSON 페이로드를 붙여넣습니다. Pushwoosh는 필드를 추출하여 페이로드 필드 드롭다운에 로드합니다.

샘플 페이로드:

{
  "id": "12345",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "loyalty_tier": "gold",
  "order_number": "ORD-001",
  "price": 99.99
}

다음으로 사용자 식별에서 Pushwoosh가 수신 요청을 사용자와 어떻게 일치시킬지 선택합니다:

User ID: 시스템에서 사용자에게 할당된 내부 식별자입니다.
이메일: 이메일 주소로 일치시킵니다.
전화: 전화번호로 일치시킵니다.
HWID: 기기, 브라우저 또는 이메일 식별자입니다.
토큰: 기기 푸시 토큰으로 일치시킵니다.

페이로드 필드에서 일치하는 값을 포함하는 필드를 선택합니다.

사용자 식별 기준 드롭다운, 페이로드 필드 선택기, 일치하는 항목이 없을 경우 새 User ID 생성 확인란

선택 사항: 페이로드 필드 아래의 확인란을 켜면 일치하는 항목이 없을 때 요청을 삭제하는 대신 새 사용자를 자동으로 생성합니다. 레이블은 선택한 식별자와 일치합니다(예: 일치하는 항목이 없을 경우 새 User ID 생성 또는 일치하는 항목이 없을 경우 새 이메일 생성). Pushwoosh는 실제 SDK 세션 이전에 기기, 브라우저 또는 푸시 토큰 식별자를 생성할 수 없으므로 HWID 및 토큰의 경우 이 확인란이 비활성화됩니다.

각 웹훅은 최소한 하나의 태그를 매핑하거나, 하나의 이벤트를 발생시키거나, 둘 다 수행해야 합니다.

프로필에 태그 추가

프로필에 태그 추가를 사용하여 페이로드 값을 일치된 사용자 프로필에 태그로 저장합니다. 더 나은 세분화를 위해 플랜 등급이나 도시와 같은 프로필 데이터를 채웁니다.

+ 태그 추가를 클릭합니다.
태그 이름에서 목록의 기존 태그를 선택하거나 새 이름을 입력합니다. Pushwoosh는 생성: <name>을 표시하여 태그를 생성할 것임을 확인합니다.
기존 태그를 선택한 경우, 유형은 해당 유형을 표시하며 변경할 수 없습니다. 새 태그를 생성한 경우, 유형을 열고 데이터 유형을 선택합니다. Pushwoosh는 이를 이 유형의 사용자별 태그로 저장합니다.
페이로드 필드에서 값을 보유하는 샘플 페이로드의 필드를 선택합니다.
채우려는 모든 태그에 대해 1-4단계를 반복합니다.

행을 제거하려면 **×**를 클릭합니다.

이벤트 기록

이벤트 기록을 사용하여 웹훅이 유효한 요청을 수신할 때 Pushwoosh 이벤트를 발생시킵니다. 발생된 이벤트는 Journey를 시작하거나 진행시킬 수 있습니다.

이벤트에서 발생시킬 Pushwoosh 이벤트를 선택합니다.
+ 속성 추가를 클릭합니다.
이벤트 속성에서 목록의 선택된 이벤트의 기존 속성을 선택하거나 새 이름을 입력합니다. Pushwoosh는 생성: <name>을 표시하여 속성을 생성할 것임을 확인합니다.
기존 속성을 선택한 경우, 유형은 해당 유형을 표시하며 변경할 수 없습니다. 새 속성을 생성한 경우, 유형을 열고 데이터 유형을 선택합니다.
페이로드 필드에서 값을 보유하는 샘플 페이로드의 필드를 선택합니다.
채우려는 모든 속성에 대해 2-5단계를 반복합니다.

행을 제거하려면 **×**를 클릭합니다.

CheckoutSuccess 이벤트가 선택되어 있고 총계(가격 유형)를 price에 매핑하는 이벤트 속성 행이 있는 이벤트 기록 섹션

활성화 및 연결

구성이 완료되면 웹훅 활성화를 클릭합니다. 웹훅 URL 창이 열립니다.

URL을 복사하여 서드파티 서비스에서 웹훅 대상으로 설정합니다.
시크릿을 복사하여 서드파티 서비스에 Authorization 헤더 값으로 붙여넣습니다. 값에는 Bearer 접두사가 포함되어 있으므로 그대로 사용합니다. Pushwoosh는 이 헤더가 없거나 일치하지 않는 모든 요청을 거부합니다.

서드파티 서비스 구성을 위한 복사 버튼이 있는 URL 및 시크릿 필드를 보여주는 웹훅 URL 창

요청 예시 블록에서 복사를 클릭하여 샘플 POST 요청을 복사합니다. 이를 사용하여 테스트 요청을 보내고 Pushwoosh가 웹훅을 수락하는지 확인하거나, 통합을 위한 템플릿으로 팀과 공유합니다.

서드파티 서비스 설정을 위한 URL, 시크릿, 요청 예시 curl 명령어가 있는 웹훅 URL 창

웹훅을 활성화하면 웹훅 목록에 활성화된 상태로 표시되고 요청을 수락하기 시작합니다.

웹훅 목록

인바운드 웹훅 목록에는 프로젝트의 모든 웹훅이 표시됩니다.

각 행에는 다음이 표시됩니다:

이름: 웹훅 이름.
상태: 활성화됨 또는 비활성화됨.
수신됨: 웹훅이 수신한 총 수신 요청 수.
마지막 수정: 웹훅이 마지막으로 변경된 시점.

검색, 상태 필터, 이름 상태 수신 마지막 수정 열이 있는 인바운드 웹훅 목록

웹훅 관리

행 메뉴를 열어 다음을 수행합니다:

설정 편집: 웹훅 구성을 열어 이름, 이벤트, 필드 매핑 및 사용자 식별을 변경할 수 있습니다.
URL 복사: URL과 시크릿이 있는 웹훅 URL 창을 열어 다시 복사할 수 있습니다.
활동 로그: 이 웹훅의 요청 로그를 엽니다.
삭제: 목록에서 웹훅을 제거합니다.

활성화된 웹훅의 경우, 비활성화를 클릭하여 구성을 삭제하지 않고 비활성화합니다. 비활성화된 웹훅의 경우, 활성화를 클릭하여 다시 요청을 수락하기 시작합니다.

활동 로그 보기

활동 로그에는 선택한 웹훅에 대한 모든 수신 요청이 표시됩니다.

요약 패널

상단에서 지난 24시간 동안의 요약을 검토합니다:

총 히트 수: 수신된 총 요청 수.
경고: 사용자가 식별(또는 생성)되었지만 구성된 태그 또는 이벤트 매핑 중 하나 이상이 적용되지 않은 요청.
실패: 잘못된 시크릿이나 식별자 필드 누락 등으로 인해 전혀 처리되지 않은 요청. 실패한 요청은 웹훅을 중지시키지 않습니다. Pushwoosh는 이후의 요청을 계속 수락하고 처리합니다.

실패 이유	의미
인증 거부됨	공유된 시크릿이 웹훅 구성과 일치하지 않습니다. 5회 연속으로 이 오류로 요청이 실패하면 Pushwoosh에서 알림을 보냅니다. 계속하려면 시크릿을 업데이트하세요. 재활성화는 필요하지 않습니다.
사용자 식별자 필드 누락	사용자 식별을 위해 매핑된 페이로드 필드가 요청에 없습니다.

요청 항목

각 항목에는 상태 아이콘, 사용자 식별자(예: User ID 또는 이메일), 요청 타임스탬프, 그리고 웹훅에 구성한 각 기능(User ID(또는 선택한 식별자), 태그, 이벤트)에 대한 확인 표시가 나타납니다. 확인 표시는 요청의 해당 부분이 성공적으로 적용되었음을 의미하며, 요청에는 확인된 항목과 실패한 항목이 혼합되어 표시될 수 있습니다. 보기를 클릭하여 수신된 전체 JSON 페이로드를 확장합니다.

User Explorer에서 웹훅으로 발생된 이벤트 및 태그 보기

웹훅 요청이 성공적으로 처리되면 Pushwoosh는 User Explorer에서 일치하는(또는 새로 생성된) 사용자에 대한 결과를 기록합니다. 이벤트가 나타나는 위치는 사용자를 식별한 방법에 따라 다릅니다:

User ID, 이메일 또는 전화: 이벤트는 사용자 프로필에 기록됩니다. 사용자를 열고 이벤트 기록으로 이동합니다.
HWID: 이벤트는 일치하는 기기에 기록됩니다. 사용자를 열고 활성 사용자 기기에서 기기를 찾은 다음 이벤트 기록 탭으로 이동합니다.

이름으로 이벤트를 찾아 확장하면 매핑된 속성(예: price 또는 products)과 웹훅 ID가 포함된 __webhook 속성을 볼 수 있습니다. 매핑된 태그는 식별자 유형에 관계없이 동일한 사용자의 사용자 개요 탭에 나타납니다.

__webhook ID와 매핑된 페이로드 필드를 포함한 확장된 속성을 가진 인바운드 웹훅 이벤트를 보여주는 User Explorer 이벤트 기록 탭

Journey에서 인바운드 웹훅 사용하기

웹훅이 활성화되고 성공적으로 이벤트를 발생시킨 후, 선택한 이벤트를 트리거 기반 Journey 진입으로 사용합니다. 웹훅이 유효한 요청을 수신하면 Pushwoosh는 매핑된 이벤트를 발생시킵니다. 이 이벤트를 진입 트리거로 사용하는 모든 Journey는 일치하는 사용자에 대해 자동으로 시작됩니다.