웹 푸시 Webhook

​

개요

• 실시간으로 알림 참여 추적
• 사용자 상호 작용을 기반으로 자동화된 워크플로 트리거
• 분석 플랫폼과 알림 데이터 동기화
• 알림 이벤트에 대한 사용자 지정 비즈니스 로직 구현

​

브라우저 지원

​

사용 가능한 Webhook 이벤트

​

notification.willDisplay

​

notification.clicked

​

notification.dismissed

​

설정 방법

• 대시보드 구성 (대부분의 사용자에게 권장)
• 사용자 지정 코드 통합

1

OneSignal 대시보드에서 설정 > 웹으로 이동합니다

2

“Enable webhooks” 토글을 활성화합니다

3

추적하려는 각 이벤트에 대한 webhook URL을 입력합니다

기존 OneSignal.init() 메서드에 webhook 구성을 추가합니다:

복사

AI에게 묻기

// 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
  }
});

​

CORS 구성

• cors: false (권장): 더 간단한 설정, 서버에서 CORS 구성이 필요하지 않음
• cors: true: 추가 헤더를 제공하지만 서버에서 CORS 지원이 필요함

• Content-Type: application/json 헤더가 필요함
• 더 쉬운 이벤트 식별을 위해 X-OneSignal-Event 헤더를 원함
• 서버가 이미 비단순 요청에 대한 CORS를 지원함

​

Webhook 요청 형식

​

표준 요청 (cors: false)

{
  "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)

Content-Type: application/json
X-OneSignal-Event: notification.clicked

​

페이로드 필드 참조

​

구현 모범 사례

​

Webhook 엔드포인트 요구 사항

• HTTPS URL만 사용(HTTP URL은 Chrome에서 차단됨)
• webhook 엔드포인트에 대한 적절한 인증/검증 구현
• 대량 알림을 처리하기 위해 속도 제한 고려

• 성공적인 처리를 위해 HTTP 200 상태 반환
• 시간 초과를 피하기 위해 10초 이내에 응답
• 중복 webhook 호출을 적절하게 처리(멱등성 구현)

​

오류 처리

// 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이 아닌 상태 코드를 반환함

​

Webhook에서 데이터 누락

​

중복 Webhook 호출

​

Webhook 제한 사항

• 이벤트당 하나의 webhook URL: 동일한 이벤트 유형에 대해 여러 webhook URL을 설정할 수 없습니다
• HTTPS만 해당: 브라우저 보안 제한으로 인해 HTTP URL은 작동하지 않습니다
• Chrome 전용 해제 추적: notification.dismissed 이벤트는 Chrome에서만 작동합니다
• 페이지 종속성: 추적이 작동하려면 사용자가 webhook 코드가 활성화된 페이지를 방문해야 합니다

​

Webhook 테스트

1. OneSignal 대시보드를 통해 테스트 알림 전송
2. 들어오는 요청에 대해 webhook 엔드포인트 모니터링
3. 페이로드 구조가 예상과 일치하는지 확인
4. 다양한 시나리오 테스트:
   • 알림 표시
   • 알림 본문 클릭
   • 작업 버튼 클릭(구성된 경우)
   • 알림 해제(Chrome만 해당)

​

다음 단계

• 분석 통합: webhook 데이터를 분석 플랫폼으로 전달
• 사용자 세분화: webhook 이벤트를 사용하여 참여를 기반으로 사용자 세그먼트 생성
• 자동화된 워크플로: 푸시 알림 상호 작용을 기반으로 이메일 캠페인 또는 앱 알림 트리거
• A/B 테스트: webhook 데이터를 사용하여 다양한 알림 전략의 효과 측정