> ## 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.
# 웹 푸시 Webhook
> 사용자가 웹 푸시 알림을 표시, 클릭 또는 해제할 때 실시간 알림을 받도록 HTTP Webhook을 설정합니다. Chrome, Firefox 및 Safari 브라우저 지원 예제가 포함된 완전한 가이드입니다.
## 개요
웹 푸시 Webhook을 사용하면 사용자가 푸시 알림과 상호 작용할 때마다 실시간 HTTP POST 알림을 받을 수 있습니다. 알림이 표시, 클릭 또는 해제되면 OneSignal은 알림 데이터와 모든 사용자 지정 매개변수를 지정된 webhook URL로 자동으로 전송합니다.
Journey Webhook의 경우 [Journey Webhook](./journeys-webhook) 페이지를 참조하세요.
**주요 이점:**
* 실시간으로 알림 참여 추적
* 사용자 상호 작용을 기반으로 자동화된 워크플로 트리거
* 분석 플랫폼과 알림 데이터 동기화
* 알림 이벤트에 대한 사용자 지정 비즈니스 로직 구현
## 브라우저 지원
| 브라우저 | 플랫폼 지원 | 사용 가능한 Webhook 이벤트 |
| ------- | ----------------------- | ------------------- |
| Chrome | macOS, Windows, Android | 모든 이벤트 (표시, 클릭, 해제) |
| Firefox | macOS, Windows, Android | 표시 및 클릭 이벤트 |
| Safari | 지원되지 않음 | 없음 |
## 사용 가능한 Webhook 이벤트
### notification.willDisplay
알림이 사용자의 화면에 나타난 직후 트리거됩니다.
**사용 사례:** 전달률 추적, 노출 데이터 로그, 후속 캠페인 트리거
### notification.clicked
사용자가 알림 본문 또는 작업 버튼을 클릭할 때 트리거됩니다.
**사용 사례:** 참여율 추적, 전환 이벤트 트리거, 사용자를 특정 콘텐츠로 리디렉션
### notification.dismissed
사용자가 알림을 적극적으로 해제하거나 자동으로 만료될 때 트리거됩니다.
**브라우저 지원:** Chrome만 해당
**사용 사례:** 해제율 추적, 알림 타이밍 최적화, 알림 콘텐츠 A/B 테스트
**중요:** 알림 본문 또는 작업 버튼을 클릭해도 해제 webhook이 트리거되지 *않습니다*.
## 설정 방법
OneSignal 대시보드에서 **설정 > 웹**으로 이동합니다
"Enable webhooks" 토글을 활성화합니다
추적하려는 각 이벤트에 대한 webhook URL을 입력합니다
기존 `OneSignal.init()` 메서드에 webhook 구성을 추가합니다:
```javascript theme={null}
// Add to your existing OneSignal initialization - do NOT call init twice
OneSignal.init({
// Your other existing settings here
webhooks: {
cors: false, // Recommended: leave as false unless you need custom headers
'notification.willDisplay': 'https://yoursite.com/webhook/display',
'notification.clicked': 'https://yoursite.com/webhook/click',
'notification.dismissed': 'https://yoursite.com/webhook/dismiss' // Chrome only
}
});
```
webhook URL이 HTTPS인지 확인하세요(Chrome의 보안 정책에 필요함).
## CORS 구성
`cors` 설정은 webhook 엔드포인트가 수신하는 헤더와 데이터를 결정합니다:
* **`cors: false` (권장):** 더 간단한 설정, 서버에서 CORS 구성이 필요하지 않음
* **`cors: true`:** 추가 헤더를 제공하지만 서버에서 CORS 지원이 필요함
**`cors: true`를 사용하는 경우:**
* `Content-Type: application/json` 헤더가 필요함
* 더 쉬운 이벤트 식별을 위해 `X-OneSignal-Event` 헤더를 원함
* 서버가 이미 비단순 요청에 대한 CORS를 지원함
## Webhook 요청 형식
### 표준 요청 (cors: false)
webhook 엔드포인트는 다음 페이로드 구조로 POST 요청을 받습니다:
```json theme={null}
{
"event": "notification.clicked",
"notificationId": "ed46884e-0e3f-4373-9e11-e28f27746d3d",
"heading": "Your notification title",
"content": "Your notification message",
"additionalData": {
"userId": "12345",
"campaignId": "summer-sale",
"customField": "customValue"
},
"actionId": "buy-now-button",
"url": "https://yoursite.com/product/123"
}
```
### 향상된 요청 (cors: true)
위와 동일한 페이로드에 다음 추가 헤더가 포함됩니다:
```http theme={null}
Content-Type: application/json
X-OneSignal-Event: notification.clicked
```
## 페이로드 필드 참조
| 필드 | 유형 | 설명 | 항상 존재 |
| ---------------- | ------ | -------------------------------- | -------------- |
| `event` | string | webhook을 트리거한 이벤트 유형 | ✅ |
| `notificationId` | string | 고유한 OneSignal 알림 식별자 | ✅ |
| `heading` | string | 알림 제목 | 제공된 경우에만 |
| `content` | string | 알림 메시지 본문 | 제공된 경우에만 |
| `additionalData` | object | 알림과 함께 전송된 사용자 지정 데이터 | 제공된 경우에만 |
| `actionId` | string | 클릭한 작업 버튼의 ID (빈 문자열 = 알림 본문 클릭) | 클릭 이벤트만 |
| `url` | string | 알림의 시작 URL | 제공된 경우에만 |
| `subscriptionId` | string | OneSignal 사용자/구독 ID | CORS 활성화된 경우에만 |
## 구현 모범 사례
### Webhook 엔드포인트 요구 사항
**보안:**
* HTTPS URL만 사용(HTTP URL은 Chrome에서 차단됨)
* webhook 엔드포인트에 대한 적절한 인증/검증 구현
* 대량 알림을 처리하기 위해 속도 제한 고려
**응답 요구 사항:**
* 성공적인 처리를 위해 HTTP 200 상태 반환
* 시간 초과를 피하기 위해 10초 이내에 응답
* 중복 webhook 호출을 적절하게 처리(멱등성 구현)
### 오류 처리
```javascript theme={null}
// Example webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
try {
const { event, notificationId, additionalData } = req.body;
// Validate required fields
if (!event || !notificationId) {
return res.status(400).json({ error: 'Missing required fields' });
}
// Process the webhook data
processNotificationEvent(req.body);
// Always respond with 200 OK
res.status(200).json({ success: true });
} catch (error) {
console.error('Webhook processing error:', error);
res.status(500).json({ error: 'Internal server error' });
}
});
```
## 일반적인 문제 및 해결 방법
### Webhook이 실행되지 않음
**가능한 원인:**
* OneSignal 초기화가 있는 모든 페이지에 webhook 코드가 없음
* 사용자가 webhook 코드를 추가한 후 webhook 코드가 있는 페이지를 방문하지 않음
* HTTPS 요구 사항이 충족되지 않음
* 서버가 200이 아닌 상태 코드를 반환함
**해결 방법:** 알림이 활성화된 모든 페이지의 OneSignal init 코드에 webhook 구성이 포함되어 있는지 확인합니다.
### Webhook에서 데이터 누락
**원인:** Webhook은 webhook 구성이 활성화된 페이지를 방문하는 사용자의 이벤트만 추적합니다.
**해결 방법:** 특정 랜딩 페이지뿐만 아니라 OneSignal이 있는 모든 페이지에 webhook 코드를 배포합니다.
### 중복 Webhook 호출
**원인:** 네트워크 문제 또는 브라우저 동작으로 인해 중복 요청이 발생할 수 있습니다.
**해결 방법:** `notificationId` 필드를 사용하여 멱등성을 구현하여 이벤트를 중복 제거합니다.
## Webhook 제한 사항
* **이벤트당 하나의 webhook URL:** 동일한 이벤트 유형에 대해 여러 webhook URL을 설정할 수 없습니다
* **HTTPS만 해당:** 브라우저 보안 제한으로 인해 HTTP URL은 작동하지 않습니다
* **Chrome 전용 해제 추적:** `notification.dismissed` 이벤트는 Chrome에서만 작동합니다
* **페이지 종속성:** 추적이 작동하려면 사용자가 webhook 코드가 활성화된 페이지를 방문해야 합니다
## Webhook 테스트
1. OneSignal 대시보드를 통해 **테스트 알림 전송**
2. 들어오는 요청에 대해 **webhook 엔드포인트 모니터링**
3. **페이로드 구조가** 예상과 일치하는지 확인
4. **다양한 시나리오 테스트:**
* 알림 표시
* 알림 본문 클릭
* 작업 버튼 클릭(구성된 경우)
* 알림 해제(Chrome만 해당)
## 다음 단계
webhook을 설정한 후 다음을 고려하세요:
* **분석 통합:** webhook 데이터를 분석 플랫폼으로 전달
* **사용자 세분화:** webhook 이벤트를 사용하여 참여를 기반으로 사용자 세그먼트 생성
* **자동화된 워크플로:** 푸시 알림 상호 작용을 기반으로 이메일 캠페인 또는 앱 알림 트리거
* **A/B 테스트:** webhook 데이터를 사용하여 다양한 알림 전략의 효과 측정