Ana içeriğe atla

​
Genel bakış

Web Push Webhook’ları, kullanıcılar push bildirimlerinizle etkileşime girdiğinde gerçek zamanlı HTTP POST bildirimleri almanızı sağlar. Bir bildirim görüntülendiğinde, tıklandığında veya kapatıldığında, OneSignal otomatik olarak bildirim verilerini ve özel parametreleri belirttiğiniz webhook URL’sine gönderir.
Journey webhook’ları için Journey webhook’ları sayfamıza bakın.
Temel Faydalar:
  • Bildirim etkileşimini gerçek zamanlı olarak izleyin
  • Kullanıcı etkileşimlerine dayalı otomatik iş akışlarını tetikleyin
  • Bildirim verilerini analitik platformunuzla senkronize edin
  • Bildirim olayları için özel iş mantığı uygulayın

​
Tarayıcı desteği

TarayıcıPlatform DesteğiKullanılabilir Webhook Olayları
ChromemacOS, Windows, AndroidTüm olaylar (görüntüleme, tıklama, kapatma)
FirefoxmacOS, Windows, AndroidGörüntüleme ve tıklama olayları
SafariDesteklenmiyorYok

​
Kullanılabilir webhook olayları

​
notification.willDisplay

Bir bildirim kullanıcının ekranında göründükten hemen sonra tetiklenir. Kullanım senaryoları: Teslimat oranlarını izleyin, gösterim verilerini kaydedin, takip kampanyalarını tetikleyin

​
notification.clicked

Bir kullanıcı bildirim gövdesine veya herhangi bir eylem düğmesine tıkladığında tetiklenir. Kullanım senaryoları: Etkileşim oranlarını izleyin, dönüşüm olaylarını tetikleyin, kullanıcıları belirli içeriğe yönlendirin

​
notification.dismissed

Bir kullanıcı bir bildirimi aktif olarak kapattığında veya otomatik olarak sona erdiğinde tetiklenir. Tarayıcı desteği: Yalnızca Chrome Kullanım senaryoları: Kapatma oranlarını izleyin, bildirim zamanlamasını optimize edin, bildirim içeriğini A/B test edin Önemli: Bildirim gövdesine veya eylem düğmelerine tıklamak kapatma webhook’unu tetiklemez.

​
Kurulum yöntemleri

  • Kontrol Paneli Yapılandırması (Çoğu Kullanıcı İçin Önerilir)
  • Özel Kod Entegrasyonu
1

OneSignal kontrol panelinizde Ayarlar > Web’e gidin
2

“Webhook’ları etkinleştir” anahtarını etkinleştirin
3

İzlemek istediğiniz her olay için webhook URL’lerinizi girin

OneSignal kontrol paneli ayarlarınızda webhook'ları etkinleştirin

Webhook URL’lerinizin HTTPS olduğundan emin olun (Chrome’un güvenlik politikaları tarafından gereklidir).

​
CORS yapılandırması

cors ayarı, webhook endpoint’inizin hangi başlıkları ve verileri alacağını belirler:
  • cors: false (Önerilir): Daha basit kurulum, sunucunuzda CORS yapılandırması gerekmez
  • cors: true: Ek başlıklar sağlar ancak sunucunuzda CORS desteği gerektirir
cors: true ne zaman kullanılır:
  • Content-Type: application/json başlığına ihtiyacınız var
  • Daha kolay olay tanımlama için X-OneSignal-Event başlığını istiyorsunuz
  • Sunucunuz zaten basit olmayan istekler için CORS’u destekliyor

​
Webhook istek formatı

​
Standart istek (cors: false)

Webhook endpoint’iniz bu yük yapısına sahip bir POST isteği alır: 
{
  "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"
}

​
Gelişmiş istek (cors: true)

Yukarıdaki yükle aynı, artı şu ek başlıklar: 
Content-Type: application/json
X-OneSignal-Event: notification.clicked

​
Yük alanı referansı

AlanTürAçıklamaHer Zaman Mevcut
eventstringWebhook’u tetikleyen olay türü✅
notificationIdstringBenzersiz OneSignal bildirim tanımlayıcısı✅
headingstringBildirim başlığıYalnızca sağlanmışsa
contentstringBildirim mesaj gövdesiYalnızca sağlanmışsa
additionalDataobjectBildirimle gönderilen özel verilerYalnızca sağlanmışsa
actionIdstringTıklanan eylem düğmesinin ID’si (boş dize = bildirim gövdesi tıklandı)Yalnızca tıklama olayları
urlstringBildirim için başlatma URL’siYalnızca sağlanmışsa
subscriptionIdstringOneSignal kullanıcı/abonelik ID’siYalnızca CORS etkin

​
İmplementasyon en iyi uygulamaları

​
Webhook endpoint gereksinimleri

Güvenlik:
  • Yalnızca HTTPS URL’leri kullanın (HTTP URL’leri Chrome tarafından engellenecektir)
  • Webhook endpoint’leriniz için uygun kimlik doğrulama/doğrulama uygulayın
  • Yüksek hacimli bildirimleri yönetmek için hız sınırlamasını göz önünde bulundurun
Yanıt gereksinimleri:
  • Başarılı işleme için HTTP 200 durumu döndürün
  • Zaman aşımlarını önlemek için 10 saniye içinde yanıt verin
  • Yinelenen webhook çağrılarını zarif bir şekilde yönetin (idempotency uygulayın)

​
Hata yönetimi

// Örnek webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
  try {
    const { event, notificationId, additionalData } = req.body;

    // Gerekli alanları doğrula
    if (!event || !notificationId) {
      return res.status(400).json({ error: 'Missing required fields' });
    }

    // Webhook verilerini işle
    processNotificationEvent(req.body);

    // Her zaman 200 OK ile yanıt ver
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

​
Yaygın sorunlar ve çözümler

​
Webhook’lar tetiklenmiyor

Olası nedenler:
  • Webhook kodu, OneSignal başlatması olan tüm sayfalarda mevcut değil
  • Kullanıcı, eklendikten sonra webhook kodu olan bir sayfayı ziyaret etmedi
  • HTTPS gereksinimi karşılanmadı
  • Sunucu 200 olmayan durum kodları döndürüyor
Çözüm: Webhook yapılandırmasının, bildirimlerin aktif olduğu tüm sayfalarda OneSignal init kodunuza dahil edildiğinden emin olun.

​
Webhook’larda eksik veri

Neden: Webhook’lar yalnızca webhook yapılandırması aktif olan sayfaları ziyaret eden kullanıcılar için olayları izler. Çözüm: Webhook kodunu yalnızca belirli açılış sayfalarına değil, OneSignal olan tüm sayfalara dağıtın.

​
Yinelenen webhook çağrıları

Neden: Ağ sorunları veya tarayıcı davranışı yinelenen isteklere neden olabilir. Çözüm: Olayları tekilleştirmek için notificationId alanını kullanarak idempotency uygulayın.

​
Webhook sınırlamaları

  • Olay başına bir webhook URL’si: Aynı olay türü için birden fazla webhook URL’si ayarlayamazsınız
  • Yalnızca HTTPS: HTTP URL’leri tarayıcı güvenlik kısıtlamaları nedeniyle çalışmaz
  • Yalnızca Chrome kapatma izleme: notification.dismissed olayı yalnızca Chrome’da çalışır
  • Sayfa bağımlılığı: İzlemenin çalışması için kullanıcıların webhook kodu aktif olan sayfaları ziyaret etmesi gerekir

​
Webhook’larınızı test etme

  1. OneSignal kontrol paneliniz aracılığıyla bir test bildirimi gönderin
  2. Gelen istekler için webhook endpoint’inizi izleyin
  3. Yük yapısının beklentilerinizle eşleştiğini doğrulayın
  4. Farklı senaryoları test edin:
    • Bildirim görüntüleme
    • Bildirim gövdesine tıklama
    • Eylem düğmelerine tıklama (yapılandırılmışsa)
    • Bildirimleri kapatma (yalnızca Chrome)

​
Sonraki adımlar

Webhook’ları kurduktan sonra, şunları göz önünde bulundurun:
  • Analitik Entegrasyonu: Webhook verilerini analitik platformunuza iletin
  • Kullanıcı Segmentasyonu: Etkileşime dayalı kullanıcı segmentleri oluşturmak için webhook olaylarını kullanın
  • Otomatik İş Akışları: Push bildirim etkileşimlerine dayalı e-posta kampanyalarını veya uygulama bildirimlerini tetikleyin
  • A/B Testi: Farklı bildirim stratejilerinin etkinliğini ölçmek için webhook verilerini kullanın