웹훅

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

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

웹훅 요소 설정 방법

웹훅 요소 추가하기

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

진입 및 대기 요소 뒤에 선택된 Amplitude 웹훅 단계가 있는 Customer Journey 캔버스

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

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

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

GET 또는 POST 메서드를 선택하기 위한 URL 필드와 REQUEST TYPE 드롭다운을 보여주는 웹훅 구성 인터페이스

헤더 구성하기

HEADERS 섹션에서 콘텐츠 유형을 설정하세요.

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

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

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

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

엔드포인트에 필요한 인증 헤더를 추가하세요. 예:

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

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

HTTP Basic 인증의 경우, 구체적으로 다음을 수행하세요:

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

웹훅 설정에서 Content-Type 및 Authorization 헤더를 보여주는 Basic 인증을 위한 Authorization 헤더 예시

헤더 값을 비밀로 표시하기

헤더 값 옆의 눈 아이콘을 클릭하여 마스킹하세요. Pushwoosh는 UI, API 응답, Journey 버전 기록 등 서비스 외부로 나갈 수 있는 모든 곳에서 해당 값을 숨깁니다.

마스킹된 Authorization 값과 비활성화된 눈 아이콘, 그리고 활성화된 눈 아이콘이 있는 마스킹되지 않은 Content-Type 값 옆에 있는 웹훅 헤더 목록

자동 마스킹. 자격 증명처럼 보이는 이름을 가진 헤더는 눈 아이콘을 클릭하지 않아도 자동으로 마스킹됩니다. 여기에는 Authorization, Proxy-Authorization, Cookie, Set-Cookie 및 token, secret, password, credential, auth 또는 api-key/api_key/apikey(하이픈, 밑줄 또는 구분자 없음)를 포함하는 모든 이름이 포함됩니다.
마스킹된 값 변경. ••••••••가 표시된 필드를 클릭하고 새 값을 입력하세요. 저장된 값을 표시하는 버튼은 없습니다. 마스크가 표시되는 동안 눈 아이콘은 잠겨 있습니다. 헤더에서 비밀 플래그를 제거하려면 먼저 새 값을 입력한 다음 아이콘을 클릭하세요.
마스킹된 헤더 이름 변경. 현재 마스크로 표시된 값을 가진 헤더의 이름을 변경하면 해당 값이 지워집니다. 새 이름으로 다시 입력하세요. 방금 입력한 값을 가진 헤더의 이름을 변경하면 해당 값이 유지됩니다.

JSON 요청 본문 추가하기

DATA 섹션에 JSON 요청 본문을 입력하세요. 요청 본문이 올바른 JSON 형식인지 확인하세요.

예시:

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

동적 데이터 및 매크로 사용하기

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

이를 위해 다음을 수행하세요:

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

기기: 사용자의 기기와 관련된 기술 정보가 필요할 때 기기 데이터를 사용하세요.
태그: 사용자 프로필에 저장된 정보를 보내고 싶을 때 태그 데이터를 사용하세요.
이벤트: 웹훅이 Journey의 트리거 이벤트에서 값을 보내야 할 때 이벤트 데이터를 사용하세요.

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

{{tag:Language}}

매크로를 복사하여 DATA 섹션의 JSON 본문에 붙여넣으세요.

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

추가 플레이스홀더 직접 입력하기

플레이스홀더는 DATA BUILDER 카테고리에서 생성하는 대신 직접 입력하는 매크로입니다. DATA BUILDER 패널은 기기, 태그 및 이벤트 데이터만 다룹니다. 대신 이 플레이스홀더를 URL, HEADERS 또는 DATA 섹션에 직접 입력하세요. 패널에는 나타나지 않습니다:

플레이스홀더	값
`{{application_code}}`	여행자가 속한 앱의 애플리케이션 코드.
`{{traveler:id}}`	Pushwoosh가 이 Journey 실행을 위해 이 여행자에게 할당하는 ID.
`{{journey:uuid}}`	이 Journey의 UUID.
`{{journey:name}}`	이 Journey의 이름.
`{{point:uuid}}`	이 Webhook 단계의 UUID.
`{{point:name}}`	이 Webhook 단계의 STEP NAME.
`{{event:name}}`	이 여행자의 Journey 진입을 트리거한 이벤트의 이름.
`{{device:platform}}`	기기의 플랫폼, 예: `Android` 또는 `iOS`.
`{{device:push_subscribed}}`	여행자가 푸시 알림을 구독했는지 여부 — `true` 또는 `false`.
`{{now}}`	현재 날짜 및 시간, ISO 8601, UTC.
`{{now:unix_ms}}`	현재 시간을 유닉스 밀리초로.
`{{tags:all}}`	여행자 기기의 모든 태그 값을 하나의 JSON 객체로. 따옴표 없이 사용하세요, 예: `"user_properties": {{tags:all}}`. 따옴표로 묶으면 객체가 이스케이프된 문자열로 변환됩니다.

JSON 본문에서 플레이스홀더 유형 유지하기

따옴표 안의 플레이스홀더는 값의 실제 유형에 관계없이 항상 JSON 문자열이 됩니다. 따옴표 없이 단독으로 사용되는 동일한 플레이스홀더는 값의 고유한 유형을 유지합니다: 숫자는 숫자로, true/false는 불리언으로, 목록은 JSON 배열이 됩니다. 따옴표 없는 플레이스홀더는 필드의 전체 값이어야 합니다 — "age": {{tag:Age}}는 작동하지만, "note": prefix{{tag:Age}}suffix는 작동하지 않습니다. 따옴표 밖의 모든 것이 입력된 그대로 작성되고 추가 문자가 JSON을 깨뜨리기 때문입니다.

{
  "age": {{tag:Age}},
  "age_as_text": "{{tag:Age}}"
}

여기서 age는 태그의 숫자 값(34)을 보내고, age_as_text는 문자열 "34"를 보냅니다. 수신 측 필드가 예상하는 것을 사용하세요. 태그에 값이 없는 경우, 따옴표 없는 플레이스홀더는 여전히 빈 문자열로 확인되며, 숫자나 false가 아닙니다. JSON 요청 본문 추가하기 아래의 참고 사항을 참조하세요.

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

데이터를 보내는 것 외에도 Webhook 단계는 서비스가 다시 보내는 응답의 값을 유지할 수 있습니다. 각 값에 이름(Attribute)을 지정합니다. 이후 단계에서는 다른 웹훅 응답 값을 사용하는 것과 동일한 방식으로 해당 이름을 사용할 수 있습니다. 예를 들어, 사용자 프로필 업데이트로 태그를 설정하거나, 서비스가 반환한 날짜로부터 시간 지연을 예약할 수 있습니다. 전체 Journey 예제는 Journey에서 웹훅 응답 데이터 사용하기를 참조하세요.

예: CRM이 사용자 ID를 반환합니다. 이를 Attribute crm_user_id로 저장합니다. 그런 다음 사용자 프로필 업데이트가 이를 태그에 씁니다.

매핑하기 전에 서비스에서 샘플 응답을 하나 받으세요. 개발자에게 문의하거나, 테스트 후 호출 로그에서 성공적인 호출을 열어 응답 본문을 확인하세요. Path를 구성하려면 해당 응답의 필드 이름이 필요합니다.

RESPONSE MAPPING 섹션에서 + ADD MAPPING을 클릭하고 캡처하려는 각 값에 대해 두 개의 필드를 채우세요:

Path: 응답 JSON 본문 내 값의 위치, 수준 사이에 점을 사용
Attribute: Journey에서 나중에 사용할 이름

웹훅 설정에서 Path 및 Attribute 필드와 매핑 추가 버튼이 있는 응답 매핑 섹션

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

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

Path를 data.user.id로 설정합니다.
Attribute를 crm_user_id로 설정합니다.

사용자가 이 단계를 통과한 후, 이후 요소들은 다른 웹훅 응답 값을 선택하는 것과 동일한 방식으로 Attribute crm_user_id를 선택할 수 있습니다.

Condition split은 이를 직접 사용할 수 없습니다. 매핑된 웹훅 값에는 유형이 없습니다. 먼저 값을 태그로 저장한 다음 해당 태그에서 분기하세요. Condition split에서 웹훅 값 비교하기를 참조하세요.

단일 필드의 경우, Path와 값은 다음과 같이 작동합니다:

객체 이름은 점으로 구분하여 작성하세요: data.user.id.
목록의 경우, 위치 번호를 사용하여 하나의 항목을 가져옵니다. 첫 번째 항목은 0이므로, results.0.code는 첫 번째 항목의 code 필드입니다. 목록의 모든 항목을 매핑하려면 배열의 모든 요소 매핑하기를 참조하세요.
목록에서 일부 항목만 매핑할 수는 없습니다. 목록의 경우 한 위치 또는 모든 항목만 가능합니다.
Pushwoosh는 서비스가 보낸 그대로 값(텍스트, 숫자 또는 true/false)을 유지합니다. 숫자 100은 숫자로 유지됩니다. 텍스트 "100"은 텍스트로 유지되며 Journey가 숫자를 예상하는 곳에서는 작동하지 않습니다. 시간 지연 날짜의 경우, 서비스는 시간 지연이 허용하는 형식을 반환해야 합니다. 19.99와 같은 소수는 가격 유형의 태그에 들어갈 수 있습니다.
응답이 유효한 JSON이 아니거나 Path가 어떤 필드와도 일치하지 않으면 해당 사용자에 대해 속성이 생성되지 않습니다. Webhook 단계는 여전히 평소와 같이 완료됩니다. 오류 배너는 없습니다. 호출 로그에서 응답 본문을 확인하고 다운스트림에서 값이 누락된 경우 Path를 수정하세요.

배열의 모든 요소 매핑하기

때때로 웹훅 응답에는 단 하나의 값만 있는 것이 아니라, 주문의 모든 제품, 장바구니의 모든 항목, 또는 검색의 모든 결과와 같은 목록이 있습니다. 응답 매핑은 일반적으로 필드당 하나의 값을 캡처하므로, 이 기능이 없으면 해당 목록에서 하나의 매핑된 값만 얻고 나머지는 손실됩니다.

목록이 있는 Path 필드에 *를 넣으세요. 그러면 Pushwoosh는 한 위치뿐만 아니라 목록의 모든 항목에서 값을 가져옵니다. 예를 들어, 목록 이름이 items이고 각 항목에 item_name이 있는 경우, Path를 items.*.item_name으로 설정하세요.

RESPONSE MAPPING에서 + ADD MAPPING을 클릭하고 목록을 *로 표시하여 평소와 같이 두 필드를 채우세요:

Path: 응답 내 값의 위치, 목록이 있는 곳에 *를 사용합니다. 예: items.*.item_name.
Attribute: 나중에 사용할 이름입니다. 여기에 무엇을 쓰느냐에 따라 결과를 어떻게 받을지 결정됩니다:
- 이름에 {n}을 포함시키면(예: item_{n}), 각 항목을 1부터 번호가 매겨진 고유한 값으로 얻을 수 있습니다: item_1, item_2, item_3 등. {n}은 이름의 어느 곳에나 위치할 수 있습니다(예: item_{n}_sku).
- {n}을 생략하면(예: item_names), 모든 항목을 쉼표로 구분된 하나의 값으로 결합합니다: Sofa, Lamp, Rug.

$Path가 items.*.item_name으로, Attribute가 item_{n}으로 설정된 응답 매핑 행$

Path 목록 위치는 0부터 시작합니다(items.0.item_name이 첫 번째 항목). {n}으로 만들어진 Attribute 이름은 1부터 시작합니다(item_1이 첫 번째 항목). 이들은 두 가지 다른 번호 매기기 방식입니다.

목록에서 하나의 항목만 필요한 경우, * 대신 Path에 숫자를 사용하세요(예: items.0.item_name).

예시

CRM이 다음과 같이 응답하는 경우:

{
  "items": [
    { "item_name": "Sofa" },
    { "item_name": "Lamp" },
    { "item_name": "Rug" }
  ]
}

Path를 items.*.item_name으로, Attribute를 item_{n}으로 설정하면 세 개의 개별 값을 얻습니다: item_1은 Sofa, item_2는 Lamp, item_3은 Rug입니다.
대신 Attribute를 item_names로 설정하면 하나의 값을 얻습니다: item_names는 Sofa, Lamp, Rug입니다.

매핑된 값은 나중에 Journey에서 다른 웹훅 응답 속성처럼 사용할 수 있습니다:

사용자 프로필 업데이트: 값을 태그에 저장
시간 지연: 응답의 날짜까지 대기
동적 콘텐츠: 메시지 콘텐츠 개인화

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

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

Pushwoosh는 응답을 최대 10초까지 기다립니다. 요청 전송 및 응답 처리를 포함한 전체 Webhook 단계는 30초로 제한됩니다.

재시도

500, 502, 503 또는 504 응답이나 연결 실패와 같은 네트워크 오류가 발생하면 Pushwoosh는 포기하기 전에 요청을 한 번 재시도합니다. 시간 초과된 요청은 재시도되지 않습니다 — 아래 요청이 실패할 때 발생하는 일을 참조하세요. 다른 비-2xx 응답도 재시도되지 않습니다.

속도 제한

Pushwoosh는 계정이 초당 보낼 수 있는 웹훅 요청 수를 제한합니다. 이 제한은 실제 트래픽 피크보다 훨씬 높게 설정되어 있어 일반적인 Journey에는 영향을 미치지 않습니다. 이를 초과하는 버스트는 실패하기 전에 잠시 공간을 기다립니다.

엔드포인트 쿨다운

엔드포인트가 연속으로 여러 번 실패하면 Pushwoosh는 모든 여행자에 대해 깨진 엔드포인트를 재시도하는 대신 잠시 동안 요청 전송을 중단합니다. 이는 30초에서 시작하여 추가 실패 시 최대 5분까지 두 배로 늘어납니다. 단 한 번의 성공적인 요청으로 이것이 해제되고 정상적인 전달이 재개됩니다.

요청이 실패할 때 발생하는 일

Webhook 요소에는 실패한 요청에 대한 별도의 분기가 없습니다. 다음 중 하나에 해당하면 이 단계에서 여행자가 Journey에서 제외됩니다:

원인	트리거
차단된 엔드포인트 주소	URL이 비공개, 내부, 루프백 또는 링크-로컬 주소(클라우드 메타데이터 엔드포인트 포함)인 경우
속도 제한	계정의 초당 웹훅 요청 제한을 초과했으며 짧은 대기 시간 동안 공간이 확보되지 않은 경우
엔드포인트 쿨다운	엔드포인트가 연속으로 여러 번 실패하여 Pushwoosh가 일시적으로 건너뛰는 경우
시간 초과	10초 이내에 응답이 없거나 단계가 30초 제한을 초과한 경우
네트워크 오류	요청이 엔드포인트에 전혀 도달할 수 없는 경우
비-2xx 응답	엔드포인트가 재시도되지 않는 오류 상태를 반환했거나, 한 번 재시도 후 다시 실패한 경우

요청 오류를 참조하세요.

여기서 여행자를 잃을 여유가 없다면, 엔드포인트가 항상 2xx 응답을 반환하도록 하고, 실패 상태는 응답 본문에 대신 넣으세요. 예를 들어 응답 매핑이 선택할 수 있는 값으로 말입니다.

이는 이전에 생성된 것을 포함하여 모든 Webhook 단계에 적용됩니다. 이제 위의 차단된 주소 규칙과 일치하는 엔드포인트 주소는 동일한 방식으로 실패하기 시작합니다.

실패한 요청과 달리, 도착했지만 깨끗하게 매핑되지 않는 응답(예: 유효하지 않은 JSON, 해결되지 않은 Path 또는 64 KB를 초과하는 본문)은 여행자를 제외시키지 않습니다. 위의 응답 매핑 아래의 참고 사항을 참조하세요.

웹훅 테스트하기

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

헤더에 여전히 저장된 마스크가 표시되면 Pushwoosh는 테스트 요청에 대해 실제 저장된 값을 채웁니다. 이 값은 브라우저에 절대 나타나지 않습니다.

이 대체는 이 정확한 단계에 이미 저장된 헤더에 대해서만 작동합니다. 아직 저장하지 않았거나 방금 복사한 단계는 마스크 뒤에 저장된 값이 없으므로 Pushwoosh는 해당 헤더 없이 테스트 요청을 보냅니다.

성공적인 테스트(또는 라이브 호출) 후, 호출 로그를 열고 행을 확장하여 응답 본문을 각 Path와 비교하세요. 필드는 Path에 있는 것과 정확히 일치해야 합니다. 요청이 성공했지만 이후 단계에 값이 없는 경우, Path가 일반적으로 응답과 일치하지 않는 것입니다. Webhook 단계는 이에 대한 오류를 표시하지 않습니다.

구성 저장하기

저장을 클릭하여 웹훅 구성을 저장하세요.

호출 로그

포인트의 드로어에서 호출 로그 탭을 열어 Pushwoosh가 이 단계에 대해 실제로 무엇을 보냈는지 확인하세요: 시간, 사용자, 결과 및 기간, 30일 전까지.

결과(성공, HTTP 오류, 응답 없음)로 필터링하거나 정확한 사용자 ID 또는 HWID로 검색하세요. 행을 클릭하여 확장하면 요청(메서드, URL 및 본문)과 결과에 따라 응답(상태 및 본문) 또는 오류 텍스트를 볼 수 있습니다. 기간은 자동 재시도에 소요된 시간을 포함하여 전체 단계를 포함합니다.