메인 콘텐츠로 건너뛰기

​
개요

웹 푸시 Webhook을 사용하면 사용자가 푸시 알림과 상호 작용할 때마다 실시간 HTTP POST 알림을 받을 수 있습니다. 알림이 표시, 클릭 또는 해제되면 OneSignal은 알림 데이터와 모든 사용자 지정 매개변수를 지정된 webhook URL로 자동으로 전송합니다.
Journey Webhook의 경우 Journey Webhook 페이지를 참조하세요.
주요 이점:
  • 실시간으로 알림 참여 추적
  • 사용자 상호 작용을 기반으로 자동화된 워크플로 트리거
  • 분석 플랫폼과 알림 데이터 동기화
  • 알림 이벤트에 대한 사용자 지정 비즈니스 로직 구현

​
브라우저 지원

브라우저플랫폼 지원사용 가능한 Webhook 이벤트
ChromemacOS, Windows, Android모든 이벤트 (표시, 클릭, 해제)
FirefoxmacOS, Windows, Android표시 및 클릭 이벤트
Safari지원되지 않음없음

​
사용 가능한 Webhook 이벤트

​
notification.willDisplay

알림이 사용자의 화면에 나타난 직후 트리거됩니다. 사용 사례: 전달률 추적, 노출 데이터 로그, 후속 캠페인 트리거

​
notification.clicked

사용자가 알림 본문 또는 작업 버튼을 클릭할 때 트리거됩니다. 사용 사례: 참여율 추적, 전환 이벤트 트리거, 사용자를 특정 콘텐츠로 리디렉션

​
notification.dismissed

사용자가 알림을 적극적으로 해제하거나 자동으로 만료될 때 트리거됩니다. 브라우저 지원: Chrome만 해당 사용 사례: 해제율 추적, 알림 타이밍 최적화, 알림 콘텐츠 A/B 테스트 중요: 알림 본문 또는 작업 버튼을 클릭해도 해제 webhook이 트리거되지 않습니다.

​
설정 방법

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

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

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

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

OneSignal 대시보드 설정에서 webhook 활성화

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 요청을 받습니다: 
{
  "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

​
페이로드 필드 참조

필드유형설명항상 존재
eventstringwebhook을 트리거한 이벤트 유형✅
notificationIdstring고유한 OneSignal 알림 식별자✅
headingstring알림 제목제공된 경우에만
contentstring알림 메시지 본문제공된 경우에만
additionalDataobject알림과 함께 전송된 사용자 지정 데이터제공된 경우에만
actionIdstring클릭한 작업 버튼의 ID (빈 문자열 = 알림 본문 클릭)클릭 이벤트만
urlstring알림의 시작 URL제공된 경우에만
subscriptionIdstringOneSignal 사용자/구독 IDCORS 활성화된 경우에만

​
구현 모범 사례

​
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이 아닌 상태 코드를 반환함
해결 방법: 알림이 활성화된 모든 페이지의 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 데이터를 사용하여 다양한 알림 전략의 효과 측정