요구 사항
- 액세스를 위해 OneSignal 영업팀에 문의합니다.
- URL 또는 IP 주소는 유효하고 HTTP 또는 HTTPS를 통해 접근 가능해야 합니다.
- 엔드포인트는 공개적으로 라우팅 가능해야 합니다 — 방화벽 뒤나 localhost에 있지 않아야 합니다.
- 도메인에는 유효한 최상위 도메인(
.com,.org,.net등)이 있어야 합니다.
설정
Journey가 생성되면 다음 단계를 따릅니다:- OneSignal 대시보드에서 데이터 > Webhooks로 이동합니다.
- 클릭하여 새 Webhook을 생성합니다.
- 다음을 정의합니다:
- HTTP 메서드 (일반적으로
POST) - 타겟 URL
- 커스텀 헤더 (예: 인증 토큰)
- 본문 콘텐츠 (일반 텍스트 또는 JSON, 선택적으로 Liquid 사용)
- HTTP 메서드 (일반적으로
허용되지 않는 헤더
다음 헤더는 설정할 수 없습니다:content-lengthreferermetadata-flavorx-google-metadata-requesthostx-onesignal로 시작하는 모든 헤더
Webhook 테스트
curl과 같은 도구를 사용하여 엔드포인트를 수동으로 테스트할 수도 있습니다:개인화
모든 Webhook 필드는 Liquid 구문을 지원하므로 사용자 및 구독 데이터를 요청에 동적으로 삽입할 수 있습니다. 사용 가능한 속성의 전체 목록은 메시지 개인화를 참조하세요.사용자 데이터 참조
Liquid 구문을 통해 Webhook 필드에서user 객체의 다음 속성을 사용할 수 있습니다:
| 속성 | 타입 | 사용법 | 테스트에서 사용 가능? |
|---|---|---|---|
| OneSignal ID | String | {{ user.onesignal_id }} | ✅ |
| External ID | String | {{ user.external_id }} | ✅ |
| Tags | Object | {{ user.tags.your_tag_key_here }} | ❌ |
| Language | String | {{ user.language }} | ✅ |
Journey에 Webhook 추가
- Webhook을 생성하고 테스트한 후 Journey를 엽니다.
- 필요한 곳에 Webhook 단계를 추가합니다.
- 이전에 구성한 Webhook을 선택합니다.
디버깅 및 로그
Webhook 통계
Webhook의 통계 탭으로 이동하여 Webhook의 성능을 확인합니다. 여기에는 다음이 포함됩니다:- 총 전송 이벤트
- 응답 시간 추세
- 상태 코드 분포
로그 탭
더 세부적인 통찰력을 위해 로그 탭에 다음이 표시됩니다:- 최근 요청/응답 데이터
- 상태 코드 및 오류 메시지
- 헤더 및 페이로드(해당하는 경우)
재시도 로직 및 비활성화 동작
OneSignal은 복구 가능한 오류(예:429 Too Many Requests)에 대해 실패한 Webhook 요청을 재시도합니다. 재시도는 지연 시간이 증가하면서 발생합니다.
재시도가 반복적으로 실패하면 Webhook이 영구적으로 실패로 표시되고 더 이상 시도하지 않습니다.
자동 비활성화
Webhook이 지속적으로 실패하면 OneSignal은 추가 문제를 방지하기 위해 비활성화합니다. 관리자는 Webhook이 비활성화되기 전과 후에 이메일 알림과 대시보드 배너를 받습니다. 근본 원인을 파악하고 다시 활성화하기 전에 Webhook을 테스트하세요. 엔드포인트는 Journey에서 생성하는 이벤트 볼륨을 처리할 수 있어야 합니다. 앱의 메시지 전송 볼륨을 검토하여 API에 필요한 처리량을 예측하세요.성능 가이드
- 느리거나 과부하된 엔드포인트(특히
429응답 반환)는 자동 비활성화를 트리거할 수 있습니다. - 이벤트를 빠르게 기록하고 타임아웃을 방지하기 위해 추가 처리를 연기하세요.
- 볼륨은 사용자 활동에 따라 확장되므로 엔드포인트가 최대 처리량을 처리할 수 있는지 확인하세요.
event.id값(헤더 또는 본문에서 사용 가능)을 사용하여 들어오는 이벤트를 중복 제거합니다.
안정성 모범 사례
- 먼저 자체 서버를 통해 라우팅하고 타사 서비스에 직접 연결하지 마세요. 이를 통해 로깅, 인증, 제한 및 대기열을 제어할 수 있습니다. 타사 서비스는 볼륨 급증 시 요청을 속도 제한하거나 차단할 수 있으며 OneSignal은 이러한 제한을 관리하지 않습니다.
- 버스트를 계획하세요. Webhook 실행은 사용자가 단계에 도달하는 즉시 발생합니다. 많은 사용자가 한 번에 Webhook 단계에 도달하면 OneSignal은 속도 제한 없이 HTTP 요청 버스트를 보냅니다. Webhook을 안정적으로 수집하고, 속도 제한 또는 일괄 처리를 적용하며, 타사 서비스에 요청을 적절히 라우팅할 수 있는 경량 API 레이어 또는 대기열 프록시 구축을 고려하세요.
- 타사 API 제한을 검토하세요. Slack, Twilio, Segment 같은 인기 도구는 공개 HTTP API를 제공하지만 각자의 속도 제한, 인증 요구 사항 및 오류 처리가 있습니다. 직접 연결하기 전에 해당 문서를 확인하세요.
Webhook 보안
요청이 OneSignal에서 오고 변조되지 않았는지 확인하려면:- HMAC 서명: Webhook 구성에 공유 비밀을 포함합니다. OneSignal은 HMAC 헤더로 각 요청에 서명하며 서버는 페이로드를 처리하기 전에 이를 검증할 수 있습니다.
- 커스텀 인증 토큰: 커스텀 인증 헤더(예:
Authorization: Bearer YOUR_SECRET_TOKEN)를 추가하고 요청을 수락하기 전에 서버 측에서 확인합니다.
FAQ
Webhook을 사용하여 OneSignal API를 호출할 수 있나요?
아니요. Journey Webhook은 외부 시스템으로 데이터를 전송하기 위한 용도로만 설계되었습니다. OneSignal API를 호출할 수 없습니다. Journey 이벤트를 기반으로 OneSignal 데이터를 업데이트하려면 Webhook을 자체 서버를 통해 라우팅하고 서버에서 OneSignal API를 호출하세요.Webhook이 자동으로 비활성화된 이유는 무엇인가요?
OneSignal은 추가 문제를 방지하기 위해 지속적으로 실패하는 Webhook을 비활성화합니다. 로그 탭에서 오류 세부 정보(상태 코드, 응답 본문)를 확인하고, 근본 원인을 수정하고, 다시 활성화하기 전에 Webhook을 테스트하세요. 일반적인 원인으로는 엔드포인트 다운타임, 인증 오류, 속도 제한이 있습니다.Webhook 이벤트를 어떻게 중복 제거하나요?
event.id 값(헤더 또는 요청 본문에서 사용 가능)을 사용하여 고유 이벤트를 식별합니다. 서버에 처리된 이벤트 ID를 저장하고 중복을 건너뜁니다. 재시도가 같은 이벤트를 두 번 이상 전달하는 경우 특히 중요합니다.
OneSignal은 Webhook 요청을 속도 제한하나요?
아니요. OneSignal은 사용자가 단계에 도달하는 즉시 속도 제한 없이 Webhook 요청을 보냅니다. 많은 사용자가 한 번에 Webhook 단계에 도달하면 엔드포인트가 요청 버스트를 받습니다. 최대 볼륨을 처리할 수 있도록 엔드포인트를 구축하거나, 대기열 프록시를 사용하여 요청을 버퍼링하고 일괄 처리하세요.Journey를 시작하지 않고 Webhook을 테스트할 수 있나요?
네. Webhook 구성의 테스트 버튼을 사용하여 샘플 요청을 보냅니다. 태그는 테스트 요청에서 사용할 수 없습니다 — 완전한 검증을 위해 라이브 Journey에서 테스트 구독을 사용하세요.관련 페이지
Journey 개요
Journey 소개 및 멀티채널 워크플로 작동 방식.
Journey 액션
대기 단계, 분기 로직, 시간 윈도우 및 분할 경로를 추가합니다.
Liquid 구문
OneSignal 메시지 및 Webhook의 Liquid 템플릿에 대한 전체 참조.
메시지 개인화
태그, Liquid 및 동적 콘텐츠를 포함한 모든 개인화 방법 개요.