> ## 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.
# Webhooks push web
> Configurez des webhooks HTTP pour recevoir des notifications en temps réel lorsque les utilisateurs affichent, cliquent ou rejettent des notifications push web. Guide complet avec exemples pour la prise en charge des navigateurs Chrome, Firefox et Safari.
## 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](./journeys-webhook).
**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
| Navigateur | Support de plateforme | Événements webhook disponibles |
| ---------- | ----------------------- | -------------------------------------------- |
| Chrome | macOS, Windows, Android | Tous les événements (affichage, clic, rejet) |
| Firefox | macOS, Windows, Android | Événements d'affichage et de clic |
| Safari | Non pris en charge | Aucun |
## É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
Naviguez vers **Paramètres > Web** dans votre tableau de bord OneSignal
Activez le bouton "Activer les webhooks"
Entrez vos URL de webhook pour chaque événement que vous souhaitez suivre
Ajoutez la configuration de webhook à votre méthode `OneSignal.init()` existante :
```javascript theme={null}
// Ajoutez à votre initialisation OneSignal existante - N'appelez PAS init deux fois
OneSignal.init({
// Vos autres paramètres existants ici
webhooks: {
cors: false, // Recommandé : laissez sur false sauf si vous avez besoin d'en-têtes personnalisés
'notification.willDisplay': 'https://votresite.com/webhook/display',
'notification.clicked': 'https://votresite.com/webhook/click',
'notification.dismissed': 'https://votresite.com/webhook/dismiss' // Chrome uniquement
}
});
```
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 :
```json theme={null}
{
"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 :
```http theme={null}
Content-Type: application/json
X-OneSignal-Event: notification.clicked
```
## Référence des champs de payload
| Champ | Type | Description | Toujours présent |
| ---------------- | ------ | ------------------------------------------------------------------------- | ----------------------------- |
| `event` | string | Type d'événement qui a déclenché le webhook | ✅ |
| `notificationId` | string | Identifiant unique de notification OneSignal | ✅ |
| `heading` | string | Titre de la notification | Seulement si fourni |
| `content` | string | Corps du message de notification | Seulement si fourni |
| `additionalData` | object | Données personnalisées envoyées avec la notification | Seulement si fournies |
| `actionId` | string | ID du bouton d'action cliqué (chaîne vide = corps de notification cliqué) | Événements de clic uniquement |
| `url` | string | URL de lancement pour la notification | Seulement si fournie |
| `subscriptionId` | string | ID utilisateur/abonnement OneSignal | CORS 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
```javascript theme={null}
// 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