> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 이벤트 스트림
> OneSignal에서 선택한 대상으로 메시지 데이터를 실시간으로 전송합니다.
이벤트 스트림을 사용하면 OneSignal에서 선택한 대상으로 메시지 데이터를 실시간으로 전송할 수 있습니다. 이벤트 스트림은 OneSignal을 마케팅 생태계 내의 다른 제품에 연결하는 훌륭한 방법입니다. 팀이 해당 메시징을 트리거하고 기록을 유지하는 등 다양한 작업을 수행할 수 있습니다.
사용 가능한 이벤트 유형에는 다음이 포함됩니다:
* 푸시 메시지 이벤트 (전송됨, 수신됨, 클릭됨, 실패, 구독 취소됨)
* 이메일 이벤트 (전송됨, 열람됨, 클릭됨, 반송됨, 구독 취소됨 등)
* SMS 이벤트 (전송됨, 실패, 구독 취소됨 등)
* 인앱 메시지 이벤트 (노출, 클릭됨 등)
* 라이브 활동 이벤트 (전송됨, 전달됨, 확인된 전달, 실패, 구독 취소됨, 클릭됨)
## 일반적인 사용 사례
* **참여 데이터 중앙 집중화** — CRM, CDP 또는 데이터 웨어하우스로 이벤트를 스트리밍하여 크로스채널 활동(열람, 클릭, 반송)이 분산된 도구 대신 한 곳에 저장되도록 합니다.
* **분석, 보고 및 규정 준수** — 트렌드 분석, 감사 또는 규제 기록 보관을 위해 모든 메시지 이벤트를 웨어하우스에 저장합니다.
* **이탈 모니터링** — 구독 취소, 반송, 해제를 자체 시스템에서 추적하여 리텐션 위험을 조기에 발견합니다.
* **외부 워크플로 트리거** — 사용자가 메시지를 열거나 클릭할 때 다른 도구에서 자동화를 실행합니다(예: 리드 점수 업데이트, 팔로업 시퀀스 시작).
* **배치 동기화 및 추가 통합 대체** — 이벤트에 실시간으로 반응하고 OneSignal을 대상에 직접 연결하여 중간 도구와 유지 관리 비용을 절감합니다.
### 기술 팀 시작 안내
이벤트 스트림 설정은 마케팅/제품 담당자(어떤 이벤트가 중요하고 어디로 보낼지 결정)와 엔지니어링 팀(수신 엔드포인트를 구축하고 스트림을 구성) 간의 공동 작업입니다. 엔지니어링 측에서 필요한 작업은 다음과 같습니다:
1. **대상 및 범위 결정** — 이벤트를 어디에 보낼지(자체 API, 데이터 웨어하우스, CDP 등), 어떤 이벤트 유형을 스트리밍할지(푸시, 이메일, SMS, IAM, 라이브 활동), 엔드포인트 크기를 적절히 조정하기 위한 메시지 볼륨 추정값을 합의합니다.
2. **HTTP 엔드포인트 설정** — POST 요청을 수락하는 공개적으로 접근 가능한 엔드포인트를 구축하거나 구성합니다. 응답 시간을 낮게 유지하기 위해 무거운 처리 없이 이벤트를 빠르게 기록해야 합니다. 성능 기대치와 엔드포인트가 뒤처질 때 어떻게 되는지에 대해서는 [재시도 / 비활성화](#retries--disabling)를 참조하세요.
3. **OneSignal에서 이벤트 스트림 구성** — **데이터 > 이벤트 스트림**에서 이벤트를 선택하고, URL과 인증 헤더를 설정하고, [이벤트 스트림 데이터](./event-streams-data) 필드와 [Liquid 구문](./using-liquid-syntax)을 사용하여 JSON 본문을 정의합니다.
4. **엔드투엔드 테스트** — 프로덕션 엔드포인트로 전환하기 전에 [webhook.site](https://webhook.site)를 사용하여 페이로드 형식과 헤더를 확인합니다([테스트](#testing) 참조).
***
## 설정
**데이터 > 이벤트 스트림 > 새 이벤트 스트림**에서 OneSignal 애플리케이션에 대한 새 이벤트 스트림을 구성할 수 있습니다.
**요구 사항**
다음 요구 사항이 충족되지 않으면 이벤트를 전송할 수 없습니다:
* 공개적으로 접근 가능한 **HTTP(S) 엔드포인트**의 유효한 URL 또는 IP 주소
* URL 및 IP 주소는 공개적으로 라우팅 가능해야 합니다
* 도메인에는 인식된 최상위 도메인(예: ".com", ".net")이 포함되어야 합니다
### 이벤트 선택
이벤트 스트림 이름을 지정하고 **이벤트 선택**을 클릭하세요.
이렇게 하면 이벤트 스트림을 트리거할 이벤트를 선택할 수 있는 이벤트 선택 페이지가 열립니다.
각 이벤트는 플랜의 메시지 이벤트 볼륨에 반영됩니다. 대규모 사용자에게 **모든** 이벤트 유형(특히 `sent`)을 스트리밍하면 할당량을 빠르게 소진할 수 있습니다 — 예를 들어, 100,000명의 사용자에게 단 한 번 전송하면 `sent` 이벤트만으로도 100,000개가 발생합니다.
볼륨 관리 방법:
* **필요한 이벤트 유형만 선택** — 예: 전송 수준 추적이 필요 없다면 `received`와 `clicked`로 충분할 수 있습니다.
* **[이벤트 스트림 필터](#event-stream-filters) 사용** — 모든 트래픽을 스트리밍하는 대신 특정 메시지나 템플릿으로 이벤트를 제한합니다.
#### 이벤트 스트림 필터
하나 이상의 메시지 또는 템플릿의 식별자를 지정하여 이벤트를 추가로 세분화할 수 있으며, 이를 통해 특정 메시지와 관련된 이벤트만 받을 수 있습니다.
템플릿 식별자는 **메시지 > 템플릿**으로 이동하여 복사할 수 있습니다. 추적하려는 템플릿 옆에서 **옵션 > 템플릿 ID 복사**를 선택하고 이벤트 스트림 필터에 붙여넣으세요.
### 이벤트 스트림 구성
이벤트 스트림에 대한 HTTP 메서드, URL을 선택하고 헤더를 추가하세요. 여기에서 OneSignal과 시스템 간의 안전한 통신을 보장하기 위해 인증을 구성해야 합니다.
URI 및 헤더에는 사용자 속성과 이벤트 스트림의 속성에서 가져온 Liquid 구문이 포함될 수 있습니다.
#### 인증 헤더
엔드포인트에 대한 요청이 실제로 OneSignal에서 온 것인지 확인하기 위해 인증 헤더를 추가할 수 있습니다. 일반적인 인증 방법은 다음과 같습니다:
* **Authorization 헤더**: `Authorization` 헤더를 추가하세요. 여기서 `YOUR_TOKEN`은 시스템 또는 타사에서 제공합니다:
* `Basic {{YOUR_TOKEN}}`
* `Bearer {{YOUR_TOKEN}}`
* `ApiKey {{YOUR_API_KEY}}`
* **사용자 지정 헤더**: 다음과 같은 사용자 지정 헤더를 추가할 수도 있습니다:
* `X-API-Key: {{YOUR_API_KEY}}`
*참고: OneSignal은 암호화 서비스를 제공하지 않습니다*
#### 구성 테스트
테스트할 수 있는 쉬운 방법을 찾고 있다면 [webhook.site](https://webhook.site)를 사용하세요. 페이지 중앙에서 "Your unique URL"을 찾으세요. 해당 URL을 복사하여 이벤트 스트림 구성의 URL 필드에 사용하세요.
#### 허용되지 않는 헤더
다음 헤더는 제한되어 있으며 설정할 수 없습니다.
* `content-length`
* `referer`
* `metadata-flavor`
* `x-google-metadata-request`
* `host`
* `x-onesignal*`
### 본문
이벤트 스트림의 본문은 JSON입니다. 본문 JSON은 개별 키/값 쌍 또는 편집 가능한 코드 블록으로 정의할 수 있습니다. 입력 방법을 변경하려면 본문 제목 아래의 첫 번째 드롭다운을 사용하고 사용자 지정 본문을 선택하세요.
오른쪽에서 이벤트 스트림 설정 중에 입력한 내용으로 작성된 cURL 요청 예시를 볼 수 있습니다
### 개인화
사전 정의된 [이벤트 스트림 데이터](./event-streams-data)를 사용하여 이벤트 스트림의 모든 필드를 개인화할 수 있습니다. 이 데이터는 [Liquid 구문](./using-liquid-syntax)을 사용하여 추가할 수 있습니다. 이를 통해 거의 모든 사용 사례에 이벤트 스트림을 사용할 수 있는 유연성을 얻을 수 있습니다.
개인화에 사용할 수 있는 모든 이벤트, 메시지 및 사용자 이벤트 데이터 목록은 [이벤트 스트림 데이터](./event-streams-data)를 참조하세요.
#### 본문 예시
드롭다운에서 "사용자 지정 본문"을 선택하세요:
```json JSON theme={null}
{
"Event Data": {
"event.kind": "{{ event.kind }}",
"event.id": "{{ event.id }}",
"event.timestamp": "{{ event.timestamp }}",
"event.datetime": "{{ event.datetime }}",
"event.app_id": "{{ event.app_id }}",
"event.subscription_device_type": "{{ event.subscription_device_type }}",
"event.subscription_id": "{{ event.subscription_id }}",
"event.onesignal_id": "{{ event.onesignal_id }}",
"event.external_id": "{{ event.external_id }}",
"event.data.page_name": "{{ event.data.page_name}}",
"event.data.page_id": "{{ event.data.page_id}}",
"event.data.target_name": "{{ event.data.target_name}}",
"event.data.target_id": "{{ event.data.target_id}}",
"event.data.failure_reason": "{{ event.data.failure_reason}}"
},
"Message Data": {
"message.id": "{{ message.id }}",
"message.name": "{{ message.name }}",
"message.title": "{{ message.title.en }}",
"message.contents": "{{ message.contents.en }}",
"message.template_id": "{{ message.template_id }}",
"message.url": "{{ message.url }}",
"message.app_url": "{{ message.app_url }}",
"message.web_url": "{{ message.web_url }}"
}
}
```
#### JSON에서 Liquid 구문 사용
JSON 내에서 Liquid 구문을 사용할 때 적절한 인용 방법은 데이터 유형에 따라 다릅니다:
**JSON 형식 지침**
* **문자열** → 따옴표로 **감싸야** 합니다.
* **숫자** → 따옴표로 **감싸지 않습니다**.
* **객체** → 따옴표로 감싸지 **않아야** 합니다.
아래 **올바른** 예시의 `//` 주석 줄은 가독성을 위한 것입니다. 실제 이벤트 스트림 본문에서는 제거하세요 — 엄격한 JSON은 `//` 주석을 허용하지 않습니다.
**예시**
**✅ 올바름** — 따옴표로 감싸기:
```liquid JSON theme={null}
{
"user_id": "{{ user.onesignal_id }}"
}
```
**❌ 잘못됨** — 따옴표가 없으면 유효하지 않은 JSON이 생성됩니다:
```liquid JSON theme={null}
{
"user_id": {{ user.onesignal_id }}
}
```
**✅ 올바름** — 따옴표 없이:
```liquid JSON theme={null}
{
"user_score": {{ user.tags.score }}
}
```
**❌ 잘못됨** — 따옴표를 사용하면 숫자가 문자열이 됩니다:
```liquid JSON theme={null}
{
"user_score": "{{ user.tags.score }}"
}
```
**✅ 올바름** — 따옴표 없이:
```liquid JSON theme={null}
{
"user_data": {{ user.tags }}
}
```
**❌ 잘못됨** — 따옴표를 사용하면 객체가 문자열이 됩니다:
```liquid JSON theme={null}
{
"user_data": "{{ user.tags }}"
}
```
**Liquid 구문에서 다국어 조건부 처리에 대한 모범 사례**
언어 기반 조건부와 관련된 문제를 방지하려면
1. **직접 언어 확인 사용**: 더 나은 호환성을 위해 `userLang`과 같은 변수가 아닌 조건부에서 항상 `user.language`를 직접 확인하세요.
2. **간단하게 시작**: 기본 구문으로 시작한 다음 점진적으로 복잡성을 추가하세요.
3. **과도한 중첩 방지**: 구문 분석 문제를 방지하기 위해 조건부를 평평하게 유지하세요.
4. **먼저 기본 구두점 테스트**: 특수 문자를 사용하기 전에 간단한 문장과 구두점으로 시작하세요.
5. **대체 사용**: 번역이 누락된 경우에 대비하여 기본 언어(예: 영어)를 확보하세요.
6. **표준 키 사용**: 신뢰성을 위해 `content/title/en`과 같은 표준 OneSignal 키를 사용하세요.
이 접근 방식은 구문 분석 오류를 최소화하고 시스템과의 호환성을 보장합니다.
Liquid 구문을 사용하여 메시지를 개인화하는 방법에 대한 세부 정보 및 옵션은 [Liquid 구문 사용 가이드](./using-liquid-syntax)를 확인하세요.
***
## 결과 및 디버깅
이벤트 스트림의 성능 모니터링 및 문제 해결:
**보고서 탭** — 전체 기간 합계, 이벤트 스트림의 현재 상태, 시간 경과에 따른 HTTP 응답 코드의 시계열 차트를 표시합니다.
| 응답 | 의미 |
| ------------- | -------------------------------------------------------------- |
| **2xx** | 이벤트가 엔드포인트에서 성공적으로 수신되었습니다. |
| **4xx / 5xx** | 엔드포인트에서 오류를 반환했습니다. 특정 상태 코드 및 응답 본문은 로그 탭에서 확인하세요. |
| **시간 초과** | 엔드포인트가 허용된 시간 내에 응답하지 않았습니다. OneSignal이 연결을 닫고 전달을 실패로 처리했습니다. |
**로그 탭** — 전체 요청 본문, 헤더 및 엔드포인트의 응답을 포함한 최근 요청 샘플을 표시합니다. 디버깅을 시작할 때 가장 좋은 곳입니다 — OneSignal이 보낸 것과 서버가 반환한 것을 정확히 확인할 수 있습니다.
페이로드 또는 구성을 조정해야 하는 경우 이벤트 스트림을 편집하고 **테스트 전송** 버튼을 사용하여 샘플 요청을 보내세요. 페이로드가 엔드포인트의 기대와 일치할 때까지 반복한 다음 라이브로 전환하세요.
### 재시도 / 비활성화
**재시도 동작** — 요청이 복구 가능한 상태(예: `429`)로 실패하면 OneSignal은 점점 늘어나는 지연으로 재시도합니다. 단일 이벤트에 대한 재시도가 계속 실패하면 해당 이벤트는 영구적으로 실패로 표시되고 더 이상 재시도되지 않습니다.
**자동 비활성화** — 엔드포인트가 많은 이벤트에 걸쳐 지속적인 실패를 반환하면 OneSignal이 전체 이벤트 스트림을 비활성화할 수 있습니다. 이 경우:
1. 앱 및 조직 관리자는 실패 볼륨이 상당해질 때(비활성화 전)와 스트림이 비활성화될 때 다시 이메일을 받습니다.
2. 대시보드의 **이벤트 스트림** 인덱스 페이지에도 배너가 표시됩니다.
3. 근본적인 문제를 수정하고 **로그** 탭 또는 [webhook.site](https://webhook.site)로 테스트한 후 스트림을 다시 활성화하세요.
**성능 지침** — 엔드포인트는 메시지 전송이 생성하는 이벤트 볼륨을 처리할 수 있어야 합니다. 백로그와 비활성화를 방지하려면:
* **이벤트를 빠르게 기록** — 무거운 인라인 처리 없이 수신 이벤트를 대기열이나 데이터 저장소에 씁니다.
* **느린 응답과 429 방지** — 일관된 느린 응답 시간이나 속도 제한 응답은 이벤트를 쌓이게 하여 OneSignal이 스트림을 비활성화하도록 합니다.
* **전송 볼륨에 맞게 크기 조정** — 100k 메시지를 보내면 선택한 이벤트 유형당 최대 100k 이벤트가 발생합니다. 플랜의 메시지 볼륨을 검토하고 적절히 프로비저닝하세요.
**중복 제거** — 전달된 각 이벤트에는 고유한 `event.id`가 포함됩니다. 동일한 이벤트가 재시도되거나 재생될 경우 시스템이 중복 제거할 수 있도록 헤더 또는 JSON 본문에 포함하세요.
### 성공을 위한 팁
* **먼저 자체 서버에 스트림을 지정하세요.** 서드파티 API에 직접 연결할 수 *있지만*, 수신 측을 제어하지 않으면 디버깅, 속도 제한 처리, 볼륨 관리가 더 어려워집니다.
* **서드파티로 전달하기 전에 버퍼링하세요.** OneSignal은 사용자가 이벤트를 트리거하는 속도로 이벤트를 전송합니다 — 대규모 전송은 외부 속도 제한을 초과하거나 비용을 증가시키는 버스트를 생성할 수 있습니다(특히 SMS 제공업체). 이벤트를 수락하고, 대기열에 넣고, 제어할 수 있는 속도로 외부 API에 전달하는 경량 서비스를 구축하세요.
* **서드파티 API 문서를 확인하세요.** 많은 서비스가 이벤트 스트림으로 대상으로 할 수 있는 공개 HTTP API를 제공합니다. 스트림을 구성하기 전에 인증, 허용된 페이로드 형식 및 속도 제한에 관한 문서를 찾아보세요.
### 메시지 이벤트 데이터 제한
Journeys 또는 API를 통해 전송된 메시지에 대한 데이터는 OneSignal에서 30일 동안만 사용할 수 있습니다. 즉, Journey 또는 API 메시지가 전송된 후 30일 이상 경과한 메시지 이벤트(클릭, 열람, 구독 취소 등)는 이벤트 스트림에서 사용할 수 없습니다. 이는 분석에서 빈 데이터 또는 누락된 데이터로 나타날 수 있습니다.
이 제한을 해결하려면 클릭/열람/구독 취소 이벤트의 `message.id`를 동일한 `message.id`를 가진 원래 `sent` 이벤트와 연관시키세요. 원래 `sent` 이벤트에는 관련 메시지 데이터(제목, 템플릿 등)가 있어야 합니다.
***
## 테스트
[webhook.site](https://webhook.site)를 사용한 엔드투엔드 테스트 안내. **Your unique URL**을 **POST** 메서드와 함께 이벤트 스트림의 **URL** 필드에 붙여넣으세요.
추적하려는 이벤트를 설정하세요. 이 예에서는 푸시 이벤트를 사용하지만 테스트에는 모두 작동합니다.
이 예에서는 위의 [본문 예시](#body)를 사용합니다.
이벤트를 저장하고 실제 환경으로 설정하세요.
이벤트를 트리거하는 메시지를 보내세요. webhook.site에서 다음 데이터와 함께 이벤트를 볼 수 있습니다:
다음을 보여줍니다:
* **Host**: 요청이 온 IP 주소입니다. 가능한 IP 목록은 [REST API 개요](/reference/rest-api-overview)를 참조하세요.
* **Request Content** 이벤트 스트림의 본문 내에서 전송된 데이터입니다.
***