# 인바운드 웹훅 통합
인바운드 웹훅을 사용하면 외부 서비스가 Pushwoosh로 직접 이벤트를 보낼 수 있습니다. 타사 시스템이 웹훅을 트리거하면 Pushwoosh는 요청을 인증하고 구독자를 식별한 다음 매핑된 이벤트를 발생시킵니다. 이 이벤트는 Journey를 시작하거나 진행시킬 수 있습니다.
인바운드 웹훅을 사용하여 자체 서버를 구축하거나 유지 관리할 필요 없이 CRM, 전자상거래 플랫폼 또는 분석 서비스와 같은 도구를 연결하세요.
각 인바운드 웹훅은 일치하는 요청이 수신되고 성공적으로 처리될 때 하나의 Pushwoosh 이벤트를 트리거합니다.
## 시작하기 전에
웹훅 설정을 열기 전에 다음을 준비하세요.
1. **웹훅이 발생시킬 Pushwoosh 이벤트를 결정합니다.** 타사 서비스에서 트리거하려는 프로젝트의 기존 이벤트를 선택합니다. 예를 들어 `CheckoutSuccess`가 있습니다. 아직 적합한 이벤트가 없다면, 들어오는 데이터로 채우고 싶은 속성을 사용하여 [새로운 이벤트를 생성](/ko/product/audience-data-and-segmentation/events/custom-events/)하세요.
2. **타사 서비스가 웹훅을 보낼 수 있는지 확인합니다.** 서비스는 새 주문이나 양식 제출과 같이 관심 있는 이벤트가 발생할 때 외부 URL로 HTTP POST 요청을 보낼 수 있어야 합니다.
3. **타사 서비스에서 샘플 JSON 페이로드를 가져옵니다.** 이것은 서비스가 각 이벤트에 대해 보내는 데이터의 작은 예시입니다. 페이로드 필드를 Pushwoosh 이벤트 속성에 매핑하는 데 필요합니다.
## 웹훅 생성하기
1. Pushwoosh 계정에서 **Settings** → **Integrations** → **Inbound webhooks**로 이동하여 **Settings**를 클릭합니다.
2. **Create webhook**을 클릭하여 설정 흐름을 엽니다.
3. 나중에 목록에서 웹훅을 식별할 수 있도록 웹훅 이름을 입력합니다.
4. 웹훅이 유효한 요청을 수신할 때 발생해야 하는 Pushwoosh 이벤트를 선택합니다. 프로젝트에 이미 존재하는 이벤트 중에서 선택할 수 있습니다. 먼저 이벤트를 생성해야 하는 경우 [이벤트](/ko/product/audience-data-and-segmentation/events/custom-events/)를 참조하세요.
5. **Match incoming data**에 타사 서비스의 샘플 JSON 페이로드를 붙여넣습니다. Pushwoosh는 페이로드 필드를 드롭다운에 자동으로 로드합니다.
샘플 페이로드:
```json
{
"user_id": "12345",
"email_address": "jane@example.com",
"mobile": "+15551234567",
"purchase_date": "2024-03-15",
"order_number": "ORD-001",
"price": 99.99,
"payment_state": "success"
}
```
6. **Identify users by**에서 Pushwoosh가 수신 요청을 사용자와 일치시키는 방법을 선택합니다:
- **User ID:** Pushwoosh의 내부 사용자 ID로 일치시킵니다.
- **Email:** 이메일 주소로 일치시킵니다.
- **Phone:** 전화번호로 일치시킵니다.
- **HWID:** 기기, 브라우저 또는 이메일 식별자로 일치시킵니다.
**Payload field**에서 일치하는 값을 포함하는 필드를 선택합니다.
7. 각 이벤트 속성을 페이로드 필드에 매핑합니다. 각 매핑 행에서:
- **Event attribute:** Pushwoosh의 속성 이름입니다. 이 이벤트에 대해 정의된 속성 중에서 선택합니다.
- **Payload field:** 값을 포함하는 수신 페이로드의 필드입니다.
예를 들어, `email`을 `email_address`에, `total`을 `price`에, `order_id`를 `order_number`에 매핑합니다.
**+ Add attribute**를 클릭하여 행을 추가하고 **×**를 클릭하여 제거합니다.
8. 구성이 완료되면 **Enable**을 클릭합니다. **Webhook URL** 창이 열립니다.
값을 복사하여 외부 시스템의 웹훅 설정에 붙여넣습니다:
- **URL**을 복사하여 타사 서비스의 웹훅 대상으로 설정합니다.
- **Secret**을 복사하여 외부 서비스에 `Authorization` 헤더 값으로 붙여넣습니다. 값에는 `Bearer` 접두사가 포함되어 있으므로 그대로 사용하세요. Pushwoosh는 이 헤더가 없거나 일치하지 않는 모든 요청을 거부합니다.
9. 이 창에는 샘플 `POST` 요청이 포함된 **Example request**도 표시됩니다. 예제 블록에서 **Copy**를 클릭하여 전체 요청을 복사합니다. 이를 사용하여 테스트 요청을 보내고 Pushwoosh가 웹훅을 수락하는지 확인하거나, 통합을 위한 템플릿으로 팀과 공유하세요.
웹훅을 활성화하면 웹훅 목록에 활성화된 상태로 표시되고 요청 수락을 시작합니다.
## 웹훅 목록
인바운드 웹훅 목록에는 프로젝트의 모든 웹훅이 표시됩니다.
각 행에는 다음이 표시됩니다:
- **Name:** 웹훅 이름.
- **Event:** 웹훅이 유효한 요청을 수신할 때 발생하는 Pushwoosh 이벤트.
- **Status:** **Enabled** 또는 **Disabled**.
- **Received:** 웹훅이 수신한 요청 수.
- **Last updated:** 웹훅이 마지막으로 변경된 시간.
## 웹훅 관리하기
행 메뉴를 열어 다음을 수행합니다:
- **Edit settings:** 웹훅 구성을 열어 이름, 이벤트, 필드 매핑 및 사용자 식별을 변경할 수 있습니다.
- **Copy URL:** **URL**과 **Secret**이 있는 **Webhook URL** 창을 열어 다시 복사할 수 있습니다.
- **Activity log:** 이 웹훅에 대한 요청 로그를 엽니다.
- **Delete:** 목록에서 웹훅을 제거합니다.
활성화된 웹훅의 경우 **Disable**을 클릭하여 구성을 삭제하지 않고 비활성화합니다. 비활성화된 웹훅의 경우 **Enable**을 클릭하여 요청 수락을 다시 시작합니다.
### 활동 로그 보기
활동 로그에는 선택한 웹훅에 대한 모든 수신 요청이 표시됩니다.
**요약 패널**
상단에서 지난 24시간 동안의 요약을 검토합니다:
- **Hits:** 수신된 총 요청 수.
- **Success:** 인증이 통과되고 사용자를 찾았으며 이벤트가 발생한 요청.
- **Failed:** 처리되지 않은 요청. 실패한 요청은 웹훅을 중지시키지 않습니다. Pushwoosh는 이후 요청을 계속 수락하고 처리합니다.
| 실패 이유 | 의미 |
| :---- | :---- |
| **인증 거부됨** | 공유된 시크릿이 웹훅 구성과 일치하지 않습니다. 5개의 연속적인 요청이 이 오류로 실패하면 Pushwoosh에서 알림을 보냅니다. 시크릿을 업데이트하여 다시 시작하세요. 재활성화는 필요하지 않습니다. |
| **사용자 식별자 필드 누락** | 사용자 식별을 위해 매핑된 페이로드 필드가 요청에 없습니다. |
**요청 항목**
각 항목에는 사용자 식별자(예: **User ID** 또는 **Email**), **Success** 또는 **Failed** 배지, 요청 타임스탬프 및 수신된 JSON 페이로드 미리보기가 표시됩니다. **Show**를 클릭하여 전체 요청 세부 정보를 확장합니다.
## User Explorer에서 웹훅으로 발생한 이벤트 보기
웹훅 요청이 성공적으로 처리되면 Pushwoosh는 [User Explorer](/ko/product/audience-data-and-segmentation/user-explorer/)에 이벤트를 기록합니다. 이벤트가 나타나는 위치는 사용자를 식별한 방법에 따라 다릅니다:
- **User ID, Email 또는 Phone:** 이벤트가 사용자 프로필에 기록됩니다. 사용자를 열고 **Events history**로 이동합니다.
- **HWID:** 이벤트가 일치하는 기기에 기록됩니다. 사용자를 열고 **Active user devices**에서 기기를 찾은 다음 **Events history** 탭으로 이동합니다.
이름으로 이벤트를 찾아 확장하여 매핑된 속성(예: `price` 또는 `products`)과 웹훅 ID가 있는 `__webhook` 속성을 확인합니다.
## Journey와 함께 인바운드 웹훅 사용하기
웹훅이 활성화되고 이벤트를 성공적으로 발생시킨 후, 선택한 이벤트를 [트리거 기반 Journey 진입](/ko/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/)으로 사용하세요. 웹훅이 유효한 요청을 수신하면 Pushwoosh는 매핑된 이벤트를 발생시킵니다. 이 이벤트를 진입 트리거로 사용하는 모든 Journey는 일치하는 사용자에 대해 자동으로 시작됩니다.
2. **Create webhook**을 클릭하여 설정 흐름을 엽니다.
3. 나중에 목록에서 웹훅을 식별할 수 있도록 웹훅 이름을 입력합니다.
4. 웹훅이 유효한 요청을 수신할 때 발생해야 하는 Pushwoosh 이벤트를 선택합니다. 프로젝트에 이미 존재하는 이벤트 중에서 선택할 수 있습니다. 먼저 이벤트를 생성해야 하는 경우 [이벤트](/ko/product/audience-data-and-segmentation/events/custom-events/)를 참조하세요.
5. **Match incoming data**에 타사 서비스의 샘플 JSON 페이로드를 붙여넣습니다. Pushwoosh는 페이로드 필드를 드롭다운에 자동으로 로드합니다.
샘플 페이로드:
```json
{
"user_id": "12345",
"email_address": "jane@example.com",
"mobile": "+15551234567",
"purchase_date": "2024-03-15",
"order_number": "ORD-001",
"price": 99.99,
"payment_state": "success"
}
```
6. **Identify users by**에서 Pushwoosh가 수신 요청을 사용자와 일치시키는 방법을 선택합니다:
- **User ID:** Pushwoosh의 내부 사용자 ID로 일치시킵니다.
- **Email:** 이메일 주소로 일치시킵니다.
- **Phone:** 전화번호로 일치시킵니다.
- **HWID:** 기기, 브라우저 또는 이메일 식별자로 일치시킵니다.
**Payload field**에서 일치하는 값을 포함하는 필드를 선택합니다.
7. 각 이벤트 속성을 페이로드 필드에 매핑합니다. 각 매핑 행에서:
- **Event attribute:** Pushwoosh의 속성 이름입니다. 이 이벤트에 대해 정의된 속성 중에서 선택합니다.
- **Payload field:** 값을 포함하는 수신 페이로드의 필드입니다.
예를 들어, `email`을 `email_address`에, `total`을 `price`에, `order_id`를 `order_number`에 매핑합니다.
**+ Add attribute**를 클릭하여 행을 추가하고 **×**를 클릭하여 제거합니다.
8. 구성이 완료되면 **Enable**을 클릭합니다. **Webhook URL** 창이 열립니다.
값을 복사하여 외부 시스템의 웹훅 설정에 붙여넣습니다:
- **URL**을 복사하여 타사 서비스의 웹훅 대상으로 설정합니다.
- **Secret**을 복사하여 외부 서비스에 `Authorization` 헤더 값으로 붙여넣습니다. 값에는 `Bearer` 접두사가 포함되어 있으므로 그대로 사용하세요. Pushwoosh는 이 헤더가 없거나 일치하지 않는 모든 요청을 거부합니다.
9. 이 창에는 샘플 `POST` 요청이 포함된 **Example request**도 표시됩니다. 예제 블록에서 **Copy**를 클릭하여 전체 요청을 복사합니다. 이를 사용하여 테스트 요청을 보내고 Pushwoosh가 웹훅을 수락하는지 확인하거나, 통합을 위한 템플릿으로 팀과 공유하세요.
웹훅을 활성화하면 웹훅 목록에 활성화된 상태로 표시되고 요청 수락을 시작합니다.
## 웹훅 목록
인바운드 웹훅 목록에는 프로젝트의 모든 웹훅이 표시됩니다.
각 행에는 다음이 표시됩니다:
- **Name:** 웹훅 이름.
- **Event:** 웹훅이 유효한 요청을 수신할 때 발생하는 Pushwoosh 이벤트.
- **Status:** **Enabled** 또는 **Disabled**.
- **Received:** 웹훅이 수신한 요청 수.
- **Last updated:** 웹훅이 마지막으로 변경된 시간.
## 웹훅 관리하기
행 메뉴를 열어 다음을 수행합니다:
- **Edit settings:** 웹훅 구성을 열어 이름, 이벤트, 필드 매핑 및 사용자 식별을 변경할 수 있습니다.
- **Copy URL:** **URL**과 **Secret**이 있는 **Webhook URL** 창을 열어 다시 복사할 수 있습니다.
- **Activity log:** 이 웹훅에 대한 요청 로그를 엽니다.
- **Delete:** 목록에서 웹훅을 제거합니다.
활성화된 웹훅의 경우 **Disable**을 클릭하여 구성을 삭제하지 않고 비활성화합니다. 비활성화된 웹훅의 경우 **Enable**을 클릭하여 요청 수락을 다시 시작합니다.
### 활동 로그 보기
활동 로그에는 선택한 웹훅에 대한 모든 수신 요청이 표시됩니다.
**요약 패널**
상단에서 지난 24시간 동안의 요약을 검토합니다:
- **Hits:** 수신된 총 요청 수.
- **Success:** 인증이 통과되고 사용자를 찾았으며 이벤트가 발생한 요청.
- **Failed:** 처리되지 않은 요청. 실패한 요청은 웹훅을 중지시키지 않습니다. Pushwoosh는 이후 요청을 계속 수락하고 처리합니다.
| 실패 이유 | 의미 |
| :---- | :---- |
| **인증 거부됨** | 공유된 시크릿이 웹훅 구성과 일치하지 않습니다. 5개의 연속적인 요청이 이 오류로 실패하면 Pushwoosh에서 알림을 보냅니다. 시크릿을 업데이트하여 다시 시작하세요. 재활성화는 필요하지 않습니다. |
| **사용자 식별자 필드 누락** | 사용자 식별을 위해 매핑된 페이로드 필드가 요청에 없습니다. |
**요청 항목**
각 항목에는 사용자 식별자(예: **User ID** 또는 **Email**), **Success** 또는 **Failed** 배지, 요청 타임스탬프 및 수신된 JSON 페이로드 미리보기가 표시됩니다. **Show**를 클릭하여 전체 요청 세부 정보를 확장합니다.
## User Explorer에서 웹훅으로 발생한 이벤트 보기
웹훅 요청이 성공적으로 처리되면 Pushwoosh는 [User Explorer](/ko/product/audience-data-and-segmentation/user-explorer/)에 이벤트를 기록합니다. 이벤트가 나타나는 위치는 사용자를 식별한 방법에 따라 다릅니다:
- **User ID, Email 또는 Phone:** 이벤트가 사용자 프로필에 기록됩니다. 사용자를 열고 **Events history**로 이동합니다.
- **HWID:** 이벤트가 일치하는 기기에 기록됩니다. 사용자를 열고 **Active user devices**에서 기기를 찾은 다음 **Events history** 탭으로 이동합니다.
이름으로 이벤트를 찾아 확장하여 매핑된 속성(예: `price` 또는 `products`)과 웹훅 ID가 있는 `__webhook` 속성을 확인합니다.
## Journey와 함께 인바운드 웹훅 사용하기
웹훅이 활성화되고 이벤트를 성공적으로 발생시킨 후, 선택한 이벤트를 [트리거 기반 Journey 진입](/ko/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/)으로 사용하세요. 웹훅이 유효한 요청을 수신하면 Pushwoosh는 매핑된 이벤트를 발생시킵니다. 이 이벤트를 진입 트리거로 사용하는 모든 Journey는 일치하는 사용자에 대해 자동으로 시작됩니다.