웹훅

개발자 지원 필요

웹훅 요소를 구성하려면 개발팀의 도움이 필요합니다. 시작하려면 이 가이드를 개발팀과 공유하세요.

웹훅을 사용하면 Journey 데이터를 분석, CRM 시스템, 마케팅 도구와 같은 외부 서비스로 보낼 수 있습니다. 다음을 수행할 수 있습니다:

• 고객이 Journey에서 특정 행동을 취했을 때 외부 시스템에 알림
• 고객 데이터를 분석 도구로 전송
• 특정 Journey 이벤트 발생 시 타사 이메일, SMS 또는 WhatsApp 트리거

참고

다양한 사용 사례 및 서비스에 대한 웹훅 구현 예시를 확인하세요: 웹훅 통합 샘플

웹훅 요소 설정 방법

웹훅 요소 추가

웹훅 요소를 캔버스로 드래그 앤 드롭합니다. 타사 서비스로 보낼 Journey 정보를 고려하여 원하는 위치에 웹훅을 배치하세요.

웹훅 단계 이름 지정 및 요청 URL 및 유형 명시

단계 이름 필드에 웹훅의 이름을 입력합니다. 웹훅이 데이터를 보내는 서비스나 사용 사례에 따라 이름을 지정하면 편리할 수 있습니다.

다음으로, URL 필드에 데이터를 보낼 요청 URL을 지정합니다. URL 필드 옆의 요청 유형 드롭다운에서 요청 유형을 GET 또는 POST로 선택합니다.

헤더 구성

헤더 섹션에서 콘텐츠 유형을 설정합니다.

기본적으로 콘텐츠 유형은 application/json입니다. 웹훅을 보내는 서비스에서 다른 콘텐츠 유형을 요구하는 경우, Content-Type 헤더 값에 적절한 유형을 입력하세요.

콘텐츠 유형의 예는 다음과 같습니다:

• x-www-form-urlencoded
• text/plain
• text/xml

필요한 경우 + 헤더 추가를 클릭하여 추가 헤더를 추가할 수 있습니다. 헤더 옆의 ‘x’ 아이콘을 클릭하여 헤더를 제거할 수 있습니다.

엔드포인트에서 요구하는 인증 헤더를 추가하세요. 예를 들면 다음과 같습니다:

• Authorization: Bearer <token>
• X-Api-Key: <key>
• Authorization: Basic <base64(user:pass)>

헤더의 정적 시크릿만 지원됩니다. Pushwoosh 측에서의 OAuth2 토큰 교환 흐름, mTLS 및 요청 서명은 지원되지 않습니다. 헤더 시크릿 대신 또는 추가로 엔드포인트를 Pushwoosh의 IP 주소로 제한할 수도 있습니다. Pushwoosh IP 주소를 참조하세요.

참고

고정된 시크릿 대신 토큰이나 ID와 같은 사용자별 값을 전달해야 하나요? 동적 데이터 매크로를 URL 또는 JSON 본문에 쿼리 매개변수나 엔드포인트가 읽는 본문 필드로 삽입하세요.

HTTP 기본 인증의 경우, 다음을 수행하세요:

1. 일반 텍스트 편집기를 열고 사용자 이름과 비밀번호를 공백 없이 콜론으로 구분하여 입력합니다. 예: myuser:mypass
2. 이 문자열을 Base64로 인코딩합니다.
3. 결과로 나온 Base64 문자열을 복사합니다 (예: bXl1c2VyOm15cGFzcw==).
4. 웹훅 설정에서 Basic <YOUR BASE64 STRING> 값으로 Authorization 헤더를 추가합니다. “Basic” 단어 뒤에 공백이 있는지 확인하세요.

JSON 요청 본문 추가

데이터 섹션에 JSON 요청 본문을 입력합니다. 요청 본문이 올바른 JSON 형식인지 확인하세요.

참고

POST 요청이 전송될 때 동적 데이터 플레이스홀더에 대한 값이 없으면 null 값이 전송됩니다.

예시:

{
  "hwid": "{{device:hwid}}"
}

동적 데이터 및 매크로 사용

데이터 빌더 패널을 사용하면 사용자, 기기, 태그 또는 이벤트 데이터와 같은 동적 정보를 JSON 요청 본문에 직접 삽입할 수 있습니다. 동적 데이터를 사용하면 Journey를 진행하는 개별 사용자에게 특정한 값을 포함할 수 있습니다.

이를 위해:

1. 카테고리를 선택합니다. 세 가지 카테고리에서 데이터를 가져올 수 있습니다:

• 기기: 사용자의 기기와 관련된 기술 정보가 필요할 때 기기 데이터를 사용합니다.

• 태그: 사용자 프로필에 저장된 정보를 보내고 싶을 때 태그 데이터를 사용합니다.

• 이벤트: 웹훅이 Journey의 트리거 이벤트 값을 보내야 할 때 이벤트 데이터를 사용합니다.

참고

트리거 이벤트의 값은 Journey의 나머지 기간 동안 여행자에게 연결된 상태로 유지되며, 시간 지연을 거쳐도 마찬가지입니다. 이 값은 여행자가 취소 이벤트, 이탈 또는 Journey가 끝날 때와 같이 Journey를 떠날 때만 손실됩니다. 여행자가 동일한 웹훅 단계를 두 번 이상 통과하면 새 응답이 이전에 매핑했던 값을 덮어씁니다.

2. 매개변수를 선택합니다 (예: HWID, 좋아하는 카테고리 등).
3. Pushwoosh는 다음과 같은 매크로를 생성합니다:

{{tag:Language}}

4. 매크로를 복사하여 데이터 섹션의 JSON 본문에 붙여넣습니다.

라이브 Journey에서 웹훅이 실행되면 Pushwoosh는 자동으로 매크로를 해당 사용자의 실제 값으로 대체합니다.

웹훅 응답 데이터를 변수에 매핑

웹훅 요소는 데이터를 보내는 것 외에도 수신한 응답에서 데이터를 캡처하여 변수로 변환할 수 있습니다. 이 변수들은 Journey의 뒷부분에서 사용될 수 있습니다. 예를 들어, 사용자 프로필 업데이트로 태그를 설정하거나, 외부 서비스에서 반환된 값을 기반으로 시간 지연을 예약할 수 있습니다. 전체 Journey 예시는 Journey에서 웹훅 응답 데이터 사용하기를 참조하세요.

응답 매핑 섹션에서 + 매핑 추가를 클릭하고 캡처하려는 각 값에 대해 두 개의 필드를 채웁니다:

• 경로: 응답 JSON 본문 내 값의 위치
• 속성: Journey의 뒷부분에서 이 값을 참조할 때 사용할 이름

예를 들어, CRM이 다음과 같이 응답하는 경우:

{
  "data": {
    "user": {
      "id": "789xyz"
    }
  }
}

해당 ID를 캡처하려면 경로를 data.user.id로, 속성을 crm_user_id로 설정합니다.

참고

매핑에 대해 알아야 할 몇 가지 사항:

• 경로는 점으로 구분된 일반 경로입니다 (객체 키 및 배열의 경우 숫자 인덱스, 예: results.0.code). 와일드카드나 필터를 지원하지 않으므로 한 번에 하나의 특정 값만 가리킬 수 있습니다.
• 값은 JSON 응답에서 온 그대로(텍스트, 숫자 또는 true/false) 저장됩니다. 유형 변환은 없습니다: 100은 숫자로 매핑되지만 "100"은 텍스트로 매핑되어 숫자 비교에서 작동하지 않습니다. 시간 지연 요소에서 값을 날짜로 사용할 계획이라면, 서비스가 시간 지연이 지원하는 날짜 형식 중 하나로 값을 반환하는지 확인하세요. 소수(예: 19.99)는 가격 유형의 태그에 저장할 수 있습니다.
• 응답이 유효한 JSON이 아니거나 경로가 아무것도 일치하지 않으면 해당 사용자에 대해 해당 변수가 생성되지 않습니다. 오류는 표시되지 않으며 웹훅 단계는 여전히 정상적으로 완료됩니다.

주의

64KB보다 큰 응답 본문은 매핑을 위해 전혀 처리되지 않습니다. 값을 매핑할 계획이라면 엔드포인트가 보내는 응답을 합리적으로 작게 유지하세요.

Journey에서 웹훅 응답 데이터 사용하기

시간 초과, 재시도 및 실패한 요청

Pushwoosh는 응답을 최대 10초 동안 기다립니다. 요청 전송 및 응답 처리를 포함한 전체 웹훅 단계는 30초로 제한됩니다. 각 여행자는 요청을 한 번 트리거하며 자동 재시도는 없습니다.

주의

웹훅 요소에는 실패한 요청을 라우팅할 별도의 분기가 없기 때문에 시간 초과, 네트워크 오류 또는 2xx가 아닌 응답은 이 단계에서 여행자를 Journey에서 이탈시킵니다. 요청 오류를 참조하세요. 여기서 여행자를 잃을 여유가 없다면, 엔드포인트가 항상 2xx 응답을 반환하도록 하고 실패 상태를 응답 본문에 대신 넣으세요. 예를 들어 응답 매핑이 선택할 수 있는 값으로 말입니다.

이는 요청 자체가 완료되지 못하는 경우에만 해당됩니다. 응답이 도착했지만 깔끔하게 매핑되지 않는 경우(예: 유효하지 않은 JSON, 해결되지 않은 경로 또는 64KB를 초과하는 본문)에는 여행자가 이탈하지 않습니다. 위의 응답 매핑 아래의 참고 사항을 참조하세요.

웹훅 테스트

웹훅 테스트를 클릭하여 웹훅 구성이 올바르고 요청이 성공적으로 전송되는지 확인합니다.

구성 저장

적용을 클릭하여 웹훅 구성을 저장합니다.