# 이벤트 스트리밍 통합

<Aside type="caution" icon="setting" title="개발자 지원 필요">
 통합을 설정하려면 개발팀의 도움이 필요합니다. 이 가이드를 개발팀과 공유해 주세요.
</Aside>

## 통합 개요

### 통합 유형

**소스:** 구성된 이벤트 트리거에 따라 Pushwoosh에서 HTTP 또는 gRPC를 통해 시스템으로 데이터가 전송됩니다.

### 통합은 어떻게 작동하나요?

Pushwoosh는 커뮤니케이션 이벤트 데이터(예: 푸시/이메일 활동)를 클라이언트가 정의한 엔드포인트로 전송합니다. 데이터는 예약된 간격으로 또는 최소 배치 크기에 도달했을 때 배치 스트림으로 전송됩니다.

데이터는 선택된 이벤트, 플랫폼 및 선택적 필터(캠페인/메시지 코드, 라이브 활동)와 일치하는 경우에만 전송됩니다. 클라이언트 엔드포인트는 상태를 수신하고 선택적으로 응답할 준비가 되어 있어야 합니다.

### 용어집

**Endpoint URL**: 요청 수신을 허용하는 서버 측 엔드포인트입니다. 클라이언트는 필요한 경우 포트를 지정할 수 있습니다.

예시:

* `https://clientdomainname.com/webhook_endpoint`  
* `https://clientdomainname.com:8081/webhook_endpoint`

### 동기화된 엔터티 목록

* 커뮤니케이션 통계 이벤트 (예: Push Sent, Email Delivered)

### 사용 사례

* **실시간 참여 추적**

푸시 전송, 이메일 열람 또는 메시지 전달과 같은 사용자 상호 작용을 실시간으로 모니터링하여 캠페인 성과에 대한 즉각적인 가시성을 확보합니다.

* **외부 분석 통합**

중앙 집중식 보고 및 분석을 위해 이벤트를 타사 분석 플랫폼으로 스트리밍합니다.

* **자동화된 사용자 워크플로우**

사용자 행동에 따라 외부 시스템(CRM 또는 마케팅 자동화 도구 등)에서 작업을 트리거합니다. 예를 들어, 사용자가 이메일을 열면 후속 메시지를 보냅니다.

## 통합 설정하기

통합을 설정하려면:

1. Pushwoosh 계정에서 **Settings > 3rd party Integrations**로 이동하여 **Event streaming integration**을 찾은 다음 **Configure**를 클릭합니다.

![Configure Event streaming integration](/integrations-event-streaming-integration-1.webp)

2. 열리는 창에서 필요한 필드를 채웁니다.

![Fill out the necessary fields](/integrations-event-streaming-integration-2.webp)

#### 엔드포인트 URL 입력

 **Endpoint URL** 필드에 프로토콜과 포트(해당하는 경우)를 포함하여 이벤트가 전송될 전체 URL을 입력합니다.
 
 **예시**

* `https://clientdomainname.com/webhook_endpoint`   
* `https://clientdomainname.com:8081/webhook\_endpoint` 


#### 이벤트 선택

   
**Events** 드롭다운에서 하나 이상의 이벤트를 선택합니다. 아무것도 선택하지 않으면 유효성 검사에 실패합니다. 이벤트 목록은 백엔드에서 관리되며 시간이 지남에 따라 변경될 수 있습니다.

#### 인증 자격 증명 제공

서버에서 요구하는 경우, **Authorization** 필드에 `Authorization` 헤더의 전체 값을 입력합니다.

예시:

* `Bearer your_token_here`  
    
* `Basic base64encoded_credentials`

<Aside>값은 `Authorization` 헤더(HTTP) 또는 gRPC 메타데이터에 **있는 그대로** 삽입됩니다. 인증 체계와 토큰 사이에 공백이 있는지 확인하세요.</Aside>

#### 전송 유형 선택

**Transport type** 드롭다운에서 이벤트 전송을 위한 전달 프로토콜을 선택합니다: **HTTP** 또는 **gRPC**. 각각 특정 동작과 구성이 있습니다.

##### HTTP

**HTTP** 전송 유형을 사용하면 Pushwoosh는 다음 조건 중 하나에 따라 데이터를 배치로 보냅니다:

* 전송 준비가 된 이벤트가 100개 이상인 경우, 또는

* 마지막 전송 이후 1시간이 경과한 경우.

데이터를 보낸 후, 성공적인 응답을 받으면 연결이 종료됩니다.

서버가 **5xx 오류**로 응답하면 Pushwoosh는 정의된 재시도 정책에 따라 요청을 재시도합니다.

**재시도 메커니즘**

| 시도 | 지연 |
| :---- | :---- |
| 1차 | 1초 |
| 2차 | 1차 시도 후 3초 |
| 3차 | 2차 시도 후 8초 |

모든 재시도가 실패하면 요청은 폐기됩니다.

**타임아웃**

요청의 기본 타임아웃은 **30초**입니다. 이는 지원팀을 통해 요청 시 사용자 지정할 수 있습니다.

<LinkCard  
  title="예시 보기" 
  href="/webhook_request_batch.json" 
  target="_blank"
  rel="noopener noreferrer"
/>

##### gRPC

gRPC 전송 유형은 데이터 전송을 위해 **양방향 스트리밍**을 사용합니다. 자세한 내용은 [gRPC 문서](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc)에서 확인하세요.

스트림은 다음 조건 중 하나가 충족될 때 열립니다:
* 전달 준비가 된 이벤트가 1,000개 이상인 경우
* 마지막 스트림이 열린 후 1시간이 경과한 경우

이벤트가 전송된 후 스트림이 닫힙니다. 이는 짧은 시간 내에 각 개별 이벤트에 대해 새 스트림이 열리지 않도록 보장합니다.

<LinkCard  
  title="protobuf 사양 보기" 
  href="/webhook.proto" 
/>

**재시도 메커니즘**  
각 이벤트에는 고유한 `uuid`가 포함됩니다. 이벤트가 실패하는 경우:

1. 응답에는 `"Success"`와 **같지 않은** `status`가 포함되어야 합니다.  
2. 요청의 원본 `uuid`가 포함되어야 합니다.

Pushwoosh는 이 응답을 기반으로 전달을 재시도합니다.

**연결 설정** 

**TLS**, **keep-alive** 또는 **재시도 정책**과 같은 고급 옵션은 지원팀을 통해 수동으로 구성되며 개발팀의 참여가 필요할 수 있습니다.

### 플랫폼 선택

**Platforms 섹션**에서 이벤트 스트리밍을 활성화할 플랫폼을 하나 이상 선택합니다.

![Select at least one platform](/integrations-event-streaming-integration-3.webp)

지원되는 플랫폼은 다음과 같습니다:

* iOS, Android, macOS, Windows, Amazon, Safari  
* Chrome, Firefox, Internet Explorer, Baidu, Huawei  
* Email, SMS, Line, Xiaomi, WhatsApp

### 고급 필터 구성

**Advanced filters** 섹션에서 필터를 사용하여 이벤트 전달 기준을 세분화합니다:

* **Live activity events:** 라이브 활동 이벤트를 수신하도록 활성화합니다. 이 이벤트에는 `live_activity_id`를 포함한 메타데이터만 포함됩니다.  
    
* **Campaign filters:** 캠페인 코드로 필터링합니다. 이러한 캠페인에 연결된 이벤트만 전달됩니다.  
    
* **Message filters:** 메시지 코드로 필터링합니다. 이러한 메시지에 연결된 이벤트만 전달됩니다.

![Set advanced filters](/integrations-event-streaming-integration-4.webp)

모든 필수 필드를 완료한 후 **Apply** 버튼을 클릭하여 통합을 저장하고 활성화합니다.
<Aside>구성 변경 사항은 제출 후 **15분 이내에** 적용됩니다.</Aside>


<Aside type="tip">
사용자 지정 타임아웃 또는 gRPC 구성과 같은 고급 설정에 대해서는 [지원팀에 문의](https://help.pushwoosh.com/hc/en-us/requests/new)하세요.
</Aside>


## 요청 세부 정보 및 예시

|            |                                                   |
|-----------------------|----------------------------------------------------------|
| **엔드포인트**          | `https://exampleclientendpoint.com/webhook_endpoint`     |
| **HTTP 요청**      | `POST`                                                   |
| **인증**    | 없음                                                       |
| **요청 유형**      | 소스                                                   |
| **요청 의미**   | 웹훅 엔드포인트로 요청 보내기                    |
| **헤더**           | `Content-Type: application/json`                         |

**요청 본문 예시**

```
{ 
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new"
}
```

**응답**  
현재 응답 코드와 본문은 무시됩니다.

## 통합이 작동하는지 어떻게 알 수 있나요?

구성된 엔드포인트에서 Pushwoosh로부터 요청을 받기 시작합니다.