Passer au contenu principal

​
Aperçu

Les webhooks push web vous permettent de recevoir des notifications HTTP POST en temps réel chaque fois que les utilisateurs interagissent avec vos notifications push. Lorsqu’une notification est affichée, cliquée ou rejetée, OneSignal envoie automatiquement les données de notification et tous les paramètres personnalisés à l’URL de webhook que vous avez spécifiée.
Pour les webhooks de parcours, consultez notre page webhooks de parcours.
Avantages clés :
  • Suivez l’engagement des notifications en temps réel
  • Déclenchez des flux de travail automatisés basés sur les interactions des utilisateurs
  • Synchronisez les données de notification avec votre plateforme d’analyse
  • Implémentez une logique métier personnalisée pour les événements de notification

​
Support des navigateurs

NavigateurSupport de plateformeÉvénements webhook disponibles
ChromemacOS, Windows, AndroidTous les événements (affichage, clic, rejet)
FirefoxmacOS, Windows, AndroidÉvénements d’affichage et de clic
SafariNon pris en chargeAucun

​
Événements webhook disponibles

​
notification.willDisplay

Déclenché immédiatement après qu’une notification apparaît sur l’écran de l’utilisateur. Cas d’usage : Suivre les taux de livraison, enregistrer les données d’impression, déclencher des campagnes de suivi

​
notification.clicked

Déclenché lorsqu’un utilisateur clique sur le corps de la notification ou sur n’importe quel bouton d’action. Cas d’usage : Suivre les taux d’engagement, déclencher des événements de conversion, rediriger les utilisateurs vers du contenu spécifique

​
notification.dismissed

Déclenché lorsqu’un utilisateur rejette activement une notification ou lorsqu’elle expire automatiquement. Support navigateur : Chrome uniquement Cas d’usage : Suivre les taux de rejet, optimiser le timing des notifications, tests A/B du contenu des notifications Important : Cliquer sur le corps de la notification ou les boutons d’action ne déclenche PAS le webhook de rejet.

​
Méthodes de configuration

  • Configuration du tableau de bord (recommandé pour la plupart des utilisateurs)
  • Intégration de code personnalisé
1
Naviguez vers Paramètres > Web dans votre tableau de bord OneSignal
2
Activez le bouton “Activer les webhooks”
3
Entrez vos URL de webhook pour chaque événement que vous souhaitez suivre

Activez les webhooks dans les paramètres de votre tableau de bord OneSignal

Assurez-vous que vos URL de webhook sont en HTTPS (requis par les politiques de sécurité de Chrome).

​
Configuration CORS

Le paramètre cors détermine quels en-têtes et données votre point de terminaison de webhook reçoit :
  • cors: false (recommandé) : Configuration plus simple, aucune configuration CORS nécessaire sur votre serveur
  • cors: true : Fournit des en-têtes supplémentaires mais nécessite la prise en charge CORS sur votre serveur
Quand utiliser cors: true :
  • Vous avez besoin de l’en-tête Content-Type: application/json
  • Vous voulez l’en-tête X-OneSignal-Event pour une identification plus facile des événements
  • Votre serveur prend déjà en charge CORS pour les requêtes non simples

​
Format de requête webhook

​
Requête standard (cors: false)

Votre point de terminaison webhook reçoit une requête POST avec cette structure de payload : 
{
  "event": "notification.clicked",
  "notificationId": "ed46884e-0e3f-4373-9e11-e28f27746d3d",
  "heading": "Votre titre de notification",
  "content": "Votre message de notification",
  "additionalData": {
    "userId": "12345",
    "campaignId": "summer-sale",
    "customField": "customValue"
  },
  "actionId": "buy-now-button",
  "url": "https://yoursite.com/product/123"
}

​
Requête améliorée (cors: true)

Même payload que ci-dessus, plus ces en-têtes supplémentaires : 
Content-Type: application/json
X-OneSignal-Event: notification.clicked

​
Référence des champs de payload

ChampTypeDescriptionToujours présent
eventstringType d’événement qui a déclenché le webhook✅
notificationIdstringIdentifiant unique de notification OneSignal✅
headingstringTitre de la notificationSeulement si fourni
contentstringCorps du message de notificationSeulement si fourni
additionalDataobjectDonnées personnalisées envoyées avec la notificationSeulement si fournies
actionIdstringID du bouton d’action cliqué (chaîne vide = corps de notification cliqué)Événements de clic uniquement
urlstringURL de lancement pour la notificationSeulement si fournie
subscriptionIdstringID utilisateur/abonnement OneSignalCORS activé uniquement

​
Meilleures pratiques d’implémentation

​
Exigences du point de terminaison webhook

Sécurité :
  • Utilisez uniquement des URL HTTPS (les URL HTTP seront bloquées par Chrome)
  • Implémentez une authentification/validation appropriée pour vos points de terminaison webhook
  • Envisagez une limitation de débit pour gérer les notifications à volume élevé
Exigences de réponse :
  • Retournez un statut HTTP 200 pour un traitement réussi
  • Répondez dans les 10 secondes pour éviter les timeouts
  • Gérez les appels de webhook en double avec élégance (implémentez l’idempotence)

​
Gestion des erreurs

// Exemple de point de terminaison webhook (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
  try {
    const { event, notificationId, additionalData } = req.body;

    // Valider les champs requis
    if (!event || !notificationId) {
      return res.status(400).json({ error: 'Champs requis manquants' });
    }

    // Traiter les données du webhook
    processNotificationEvent(req.body);

    // Toujours répondre avec 200 OK
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Erreur de traitement du webhook:', error);
    res.status(500).json({ error: 'Erreur interne du serveur' });
  }
});

​
Problèmes courants et solutions

​
Les webhooks ne se déclenchent pas

Causes possibles :
  • Le code webhook n’est pas présent sur toutes les pages avec l’initialisation OneSignal
  • L’utilisateur n’a pas visité une page avec le code webhook après son ajout
  • L’exigence HTTPS n’est pas satisfaite
  • Le serveur retourne des codes de statut non-200
Solution : Assurez-vous que la configuration webhook est incluse dans votre code init OneSignal sur toutes les pages où les notifications sont actives.

​
Données manquantes dans les webhooks

Cause : Les webhooks ne suivent que les événements pour les utilisateurs qui visitent des pages avec la configuration webhook active. Solution : Déployez le code webhook sur toutes les pages avec OneSignal, pas seulement sur des pages de destination spécifiques.

​
Appels de webhook en double

Cause : Des problèmes de réseau ou le comportement du navigateur peuvent causer des requêtes en double. Solution : Implémentez l’idempotence en utilisant le champ notificationId pour dédupliquer les événements.

​
Limitations des webhooks

  • Une URL de webhook par événement : Vous ne pouvez pas définir plusieurs URL de webhook pour le même type d’événement
  • HTTPS uniquement : Les URL HTTP ne fonctionneront pas en raison des restrictions de sécurité du navigateur
  • Suivi du rejet Chrome uniquement : L’événement notification.dismissed ne fonctionne que dans Chrome
  • Dépendance de page : Les utilisateurs doivent visiter des pages avec le code webhook actif pour que le suivi fonctionne

​
Tester vos webhooks

  1. Envoyez une notification de test via votre tableau de bord OneSignal
  2. Surveillez votre point de terminaison webhook pour les requêtes entrantes
  3. Vérifiez que la structure du payload correspond à vos attentes
  4. Testez différents scénarios :
    • Affichage de notification
    • Clic sur le corps de la notification
    • Clic sur les boutons d’action (si configurés)
    • Rejet des notifications (Chrome uniquement)

​
Étapes suivantes

Après avoir configuré les webhooks, envisagez :
  • Intégration d’analyses : Transférez les données de webhook vers votre plateforme d’analyse
  • Segmentation des utilisateurs : Utilisez les événements webhook pour créer des segments d’utilisateurs basés sur l’engagement
  • Flux de travail automatisés : Déclenchez des campagnes par email ou des notifications d’application basées sur les interactions avec les notifications push
  • Tests A/B : Utilisez les données de webhook pour mesurer l’efficacité de différentes stratégies de notification