이벤트 스트리밍 통합

개발자 지원 필요

통합을 설정하려면 개발팀의 도움이 필요합니다. 이 가이드를 개발팀과 공유해 주세요.

통합 개요

통합 유형

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

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

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

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

용어집

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

예시:

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

동기화된 엔터티 목록

• 통신 통계 이벤트 (예: Push Sent, Email Delivered)
• Post 이벤트: postEvent를 통해 앱이 Pushwoosh로 보내는 이벤트로, 통신 통계 이벤트와 별도로 스트리밍됩니다.

사용 사례

• 실시간 참여 추적

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

• 외부 분석 통합

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

• 자동화된 사용자 워크플로

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

• 기기 목록 동기화

더 이상 메시지를 받을 수 없는 기기를 자체 데이터베이스에서 제거합니다. 등록 해제된 기기를 시스템에 동기화를 참조하세요.

통합 설정

통합을 설정하려면:

1. Pushwoosh 계정에서 설정 > 타사 통합으로 이동하여 이벤트 스트리밍 통합을 찾은 다음 구성을 클릭합니다.

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

엔드포인트 URL 입력

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

예시

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

이벤트 선택

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

인증 자격 증명 제공

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

예시:

• Bearer your_token_here

• Basic base64encoded_credentials

참고

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

전송 유형 선택

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

HTTP

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

• 최소 100개의 이벤트가 전송 준비되었거나,

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

데이터를 보낸 후 성공적인 응답을 받으면 연결이 닫힙니다.

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

재시도 메커니즘

시도	지연
1번째	1초
2번째	1번째 시도 후 3초
3번째	2번째 시도 후 8초

모든 재시도가 실패하면 요청은 폐기됩니다. 엔드포인트가 이벤트를 하나도 수락하지 못한 채 24시간 동안 계속 실패하면 Pushwoosh는 통합을 일시 중지합니다. 일시 중지된 통합을 참조하세요.

시간 초과

요청의 기본 시간 초과는 30초입니다. 지원팀을 통해 요청 시 사용자 지정할 수 있습니다.

예시 보기

gRPC

gRPC 전송 유형은 데이터 전송에 양방향 스트리밍을 사용합니다. 자세한 내용은 gRPC 문서를 참조하세요.

다음 조건 중 하나가 충족되면 스트림이 열립니다:

• 최소 1,000개의 이벤트가 전달 준비된 경우
• 마지막 스트림이 열린 후 1시간이 경과한 경우

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

protobuf 사양 보기

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

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

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

연결 설정

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

post 이벤트 활성화

이 토글은 기본적으로 꺼져 있으므로 통신 통계 이벤트만 스트리밍됩니다. postEvent를 통해 앱이 Pushwoosh로 보내는 이벤트도 스트리밍하려면 post 이벤트 허용 토글을 켭니다.

나타나는 Post 이벤트 필드에서 계정의 어떤 이벤트를 스트리밍할지 선택합니다. 토글이 켜져 있는 동안에는 최소 하나의 이벤트가 필요합니다. 계정이 아직 이벤트를 보내지 않았다면, postEvent를 한 번 이상 호출할 때까지 이 목록은 비어 있습니다.

참고

Post 이벤트는 위에서 입력한 동일한 엔드포인트 URL로 전송되며 플랫폼에 관계없이 도달합니다. 아래의 플랫폼 및 고급 필터 섹션은 post 이벤트가 아닌 통신 통계 이벤트에만 적용됩니다.

인앱 노출 및 클릭도 PW_InAppShow 및 PW_InAppClicked로 이 post 이벤트 스트림을 통해 전송됩니다. 다른 post 이벤트와 마찬가지로, 각 이벤트는 계정에서 한 번 이상 발생한 후에만 Post 이벤트 목록에 나타납니다.

플랫폼 선택

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

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

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

고급 필터 구성

고급 필터 섹션에서 필터를 사용하여 이벤트 전달 기준을 구체화합니다:

• 라이브 활동 이벤트: 라이브 활동 이벤트를 수신하도록 활성화합니다. 이러한 이벤트에는 live_activity_id를 포함한 메타데이터만 포함됩니다.

• 캠페인 필터: 캠페인 코드로 필터링합니다. 이러한 캠페인에 연결된 이벤트만 전달됩니다.

• 메시지 필터: 메시지 코드로 필터링합니다. 이러한 메시지에 연결된 이벤트만 전달됩니다.

모든 필수 필드를 완료한 후 적용 버튼을 클릭하여 통합을 저장하고 활성화합니다.

참고

구성 변경 사항은 제출 후 15분 이내에 적용됩니다.

팁

사용자 지정 시간 초과 또는 gRPC 구성과 같은 고급 설정에 대해서는 지원팀에 문의하세요.

요청 세부 정보 및 예시

엔드포인트	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",
  "attributes": null
}

속성

통신 통계 이벤트 중에서 attributes는 푸시 이벤트에 대해서만 채워지며, 푸시가 전송된 플랫폼에 대한 채널별 콘텐츠(Android, iOS 등)를 포함합니다. 이메일 및 SMS 이벤트는 최상위 필드(event_name, platform, payload 등)만 전달합니다. 이러한 이벤트의 경우 attributes는 null입니다. 채워진 attributes 객체 내에서 이벤트 자체 플랫폼 외부의 필드는 빈 값으로 전송되는 대신 생략됩니다. 전체 필드 목록은 webhook.proto를 참조하세요.

post 이벤트는 대신 attributes.event_attributes에 속성 키/값 쌍을 전달합니다. post 이벤트는 메시지나 캠페인에 연결되지 않으므로 message_code와 payload는 비어 있습니다.

주의

attributes.geozone은 더 이상 사용되지 않습니다. 소스 속성은 숫자가 아닌 객체이므로 이 필드는 실제 값을 전달한 적이 없습니다. 대신 attributes.geozone_data에서 실제 지오존을 읽으십시오. 기존 필드는 기존 gRPC 스텁이 있는 클라이언트를 위해 계약에 남아 있습니다.

응답
응답 본문은 무시됩니다. HTTP 전송에서는 응답 코드에 따라 이벤트가 전달된 것으로 간주되는지가 결정됩니다. 2xx 코드는 엔드포인트가 이벤트를 수락했음을 의미합니다.

등록 해제된 기기를 시스템에 동기화

CRM이나 고객 데이터 플랫폼 등에 기기 목록의 자체 사본을 보관하는 경우 PW_DeviceUnregistered post 이벤트를 스트리밍하여 Pushwoosh가 더 이상 도달할 수 없는 기기를 찾으세요. Pushwoosh는 기기가 푸시 구독을 잃을 때 이 이벤트를 보냅니다. 원인은 PW_DeviceUnregistered를 참조하세요.

이미 설정된 통합에서 시작합니다. 엔드포인트 URL이 입력되어 있고 플랫폼이 하나 이상 선택되어 있어야 합니다. 그런 다음:

1. 통합 설정에서 post 이벤트 허용을 켭니다. post 이벤트 활성화를 참조하세요.
2. Post 이벤트 필드에서 PW_DeviceUnregistered를 선택합니다.
3. 푸시 토큰을 받는 기기도 파악하려면 PW_DeviceRegistered를 선택합니다.
4. 적용을 클릭합니다. 변경 사항은 15분 이내에 적용됩니다.

다른 post 이벤트와 마찬가지로 PW_DeviceUnregistered는 계정에서 한 번 이상 발생한 후에만 Post 이벤트 목록에 나타납니다. post 이벤트 활성화를 참조하세요.

이벤트를 처리할 때 다음 제한 사항에 유의하세요.

• 푸시 토큰이 아닌 hwid 또는 user_id로 기기를 매칭하세요. 이벤트에는 기기의 hwid, user_id, 플랫폼이 포함되지만 푸시 토큰과 등록 해제 사유는 포함되지 않습니다. 만료된 토큰과 SDK를 통한 등록 해제는 똑같이 보입니다.
• 같은 기기가 새 토큰을 받아도 이벤트가 전송되지 않습니다. PW_DeviceRegistered는 푸시 토큰이 없는 기기가 토큰을 받을 때만 발생합니다. 푸시 토큰 기준으로 기기를 저장하는 목록에는 더 이상 작동하지 않는 토큰이 남습니다. 기기가 새 토큰을 받을 때 두 이벤트 모두 발생하지 않기 때문입니다.
• 이메일 수신 거부로 기기가 삭제되지는 않습니다. 이메일의 경우 주소는 기기에 그대로 남고 Pushwoosh는 이를 수신 거부로 표시하기만 합니다. 사용자가 이메일의 링크를 통해 수신을 거부한 경우 attributes.event_attributes에는 해당 이메일의 message_code와 campaign_id도 포함됩니다.

모든 HTTP 재시도에 실패한 배치는 폐기되므로 일부 이벤트는 엔드포인트에 도달하지 못할 수 있습니다. 이러한 기기를 찾으려면 타겟팅하는 기기의 세그먼트를 CSV로 내보내 기기 목록과 주기적으로 비교하세요. 세그먼트를 내보내려면 역할에 Personal data 권한이 있어야 합니다. 엔드포인트가 24시간 동안 계속 실패하면 통합이 일시 중지되고 이벤트 수신이 중단됩니다. 일시 중지된 통합을 참조하세요.

일시 중지된 통합

HTTP 엔드포인트로의 전송이 24시간 동안 계속 실패하고 그 기간 동안 엔드포인트가 이벤트를 하나도 수락하지 않으면 Pushwoosh는 통합을 일시 중지합니다:

• Pushwoosh는 엔드포인트로 이벤트 전송을 중단합니다.
• 전송 대기 중인 이벤트는 폐기됩니다. 일시 중지 기간의 이벤트는 나중에도 전송되지 않습니다.
• 계정 소유자에게 일시 중지에 대한 이메일이 발송됩니다. 통합 설정에는 일시 중지가 표시되지 않으므로 이 이메일이 유일한 알림입니다.

엔드포인트가 2xx 응답 코드를 반환하면 이벤트가 수락된 것으로 간주됩니다. 부분적인 실패로는 통합이 일시 중지되지 않습니다. 이벤트가 하나라도 수락되면 24시간 카운트가 다시 시작됩니다. gRPC 전송을 사용하는 통합은 일시 중지되지 않습니다.

스트리밍을 재개하려면:

1. 엔드포인트에 연결할 수 있고 2xx 응답 코드를 반환하는지 확인합니다.
2. 설정 > 타사 통합으로 이동하여 이벤트 스트리밍 통합을 찾은 다음 구성을 클릭합니다.
3. 적용을 클릭합니다. 설정을 변경할 필요는 없습니다. 스트리밍은 15분 이내에 재개됩니다.

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

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