Passer au contenu principal
Les webhooks de Journey envoient des requêtes HTTP depuis une étape de Journey vers vos serveurs ou tout endpoint publiquement accessible. Vous configurez la méthode HTTP, l’URL, les en-têtes et le contenu du corps. Les requêtes peuvent être personnalisées avec des données spécifiques à l’utilisateur via la syntaxe Liquid, vous permettant de synchroniser les événements de Journey avec des CRM, des plateformes d’analyse ou des backends personnalisés en temps réel.

​
Prérequis

  • Contactez l’équipe commerciale OneSignal pour l’accès.
  • L’URL ou l’adresse IP doit être valide et accessible via HTTP ou HTTPS.
  • Les endpoints doivent être publiquement routables — pas derrière un pare-feu ou sur localhost.
  • Les domaines doivent avoir un domaine de premier niveau valide (.com, .org, .net, etc.).
Les webhooks de Journey ne peuvent pas appeler les API OneSignal. Ils sont conçus uniquement pour envoyer des données à des systèmes externes.

​
Configuration

Une fois votre Journey créé, suivez ces étapes :
  1. Accédez à Données > Webhooks dans le tableau de bord OneSignal.
  2. Cliquez pour créer un nouveau webhook.
  3. Définissez les éléments suivants :
    • Méthode HTTP (généralement POST)
    • URL cible
    • En-têtes personnalisés (par exemple, tokens d’authentification)
    • Contenu du corps (texte brut ou JSON, en utilisant optionnellement Liquid)
Formulaire de configuration du webhook avec les champs méthode HTTP, URL, en-têtes et corps

​
En-têtes non autorisés

Vous ne pouvez pas définir les en-têtes suivants :
  • content-length
  • referer
  • metadata-flavor
  • x-google-metadata-request
  • host
  • Tout en-tête commençant par x-onesignal

​
Tester les webhooks

Vous pouvez également tester votre endpoint manuellement à l’aide d’un outil comme curl : 
curl -X POST https://yourserver.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "abc123" }'
Utile pour valider que votre endpoint est accessible et fonctionnel avant de l’ajouter à un Journey.

​
Personnalisation

Tous les champs de webhook prennent en charge la syntaxe Liquid, vous permettant d’insérer dynamiquement des données utilisateur et d’abonnement dans la requête. Consultez la Personnalisation des messages pour la liste complète des propriétés disponibles.

​
Référence des données utilisateur

Les propriétés suivantes de l’objet user sont disponibles dans les champs de webhook via la syntaxe Liquid :
PropriétéTypeUtilisationDisponible en test ?
OneSignal IDString{{ user.onesignal_id }}✅
External IDString{{ user.external_id }}✅
TagsObject{{ user.tags.your_tag_key_here }}❌
LanguageString{{ user.language }}✅
Les tags ne sont pas disponibles lors du test des webhooks en dehors d’un Journey actif. Utilisez les Abonnements de test pour valider le comportement avant la mise en production.

​
Ajouter un webhook à un Journey

  1. Après avoir créé et testé votre webhook, ouvrez votre Journey.
  2. Ajoutez une étape Webhook où nécessaire.
  3. Sélectionnez le webhook que vous avez configuré précédemment.
Chaque fois qu’un utilisateur atteint cette étape, le webhook se déclenche avec ses données personnalisées.
Canvas de Journey avec une étape webhook connectée entre des étapes de message

​
Débogage et journaux

​
Statistiques du webhook

Accédez à l’onglet Statistiques du webhook pour voir les performances de votre webhook. Cela inclut :
  • Total d’événements envoyés
  • Tendances du temps de réponse
  • Distribution des codes de statut
Onglet statistiques du webhook avec le nombre d'événements, les tendances du temps de réponse et la distribution des codes de statut

​
Onglet Journaux

Pour des informations plus détaillées, l’onglet Journaux affiche :
  • Données de requête/réponse récentes
  • Codes de statut et messages d’erreur
  • En-têtes et charges utiles (le cas échéant)
Onglet journaux du webhook avec les requêtes récentes, les codes de statut et les charges utiles

​
Logique de nouvelle tentative et comportement de désactivation

OneSignal réessaie les requêtes webhook échouées pour les erreurs récupérables (par exemple, 429 Too Many Requests). Les nouvelles tentatives se produisent avec des délais croissants. Si les nouvelles tentatives échouent à plusieurs reprises, le webhook est marqué comme définitivement échoué et aucune autre tentative n’est effectuée.

​
Désactivation automatique

Si un webhook échoue de manière constante, OneSignal le désactive pour éviter d’autres problèmes. Les administrateurs reçoivent des alertes par e-mail et une bannière dans le tableau de bord avant et après la désactivation d’un webhook. Identifiez la cause principale et testez le webhook avant de le réactiver. Votre endpoint doit être capable de gérer le volume d’événements produit par votre Journey. Examinez le volume d’envoi de messages de votre application pour estimer le débit nécessaire à votre API.

​
Conseils de performance

  • Les endpoints lents ou surchargés (surtout ceux renvoyant des réponses 429) peuvent déclencher la désactivation automatique.
  • Enregistrez les événements rapidement et différez le traitement supplémentaire pour éviter les délais d’attente.
  • Le volume évolue avec l’activité des utilisateurs — assurez-vous que votre endpoint peut gérer le débit maximal.
  • Utilisez la valeur event.id (disponible en en-tête ou dans le corps) pour dédupliquer les événements entrants.

​
Meilleures pratiques de fiabilité

  • Routez d’abord via votre propre serveur, pas directement vers des services tiers. Cela vous donne le contrôle sur la journalisation, l’authentification, la limitation et la mise en file d’attente. Les services tiers peuvent limiter ou bloquer les requêtes lors des pics de volume, et OneSignal ne gère pas ces limites.
  • Planifiez les rafales. L’exécution du webhook se produit immédiatement lorsque les utilisateurs atteignent l’étape. Si de nombreux utilisateurs atteignent une étape webhook en même temps, OneSignal envoie une rafale de requêtes HTTP sans limitation de débit. Envisagez de créer une couche API légère ou un proxy de mise en file d’attente capable d’ingérer les webhooks de manière fiable, d’appliquer des limites de débit ou du traitement par lots, et de router les requêtes vers vos services tiers de manière appropriée.
  • Vérifiez les limites des API tierces. Les outils populaires comme Slack, Twilio et Segment offrent des API HTTP publiques, mais ont leurs propres limites de débit, exigences d’authentification et gestion des erreurs. Consultez leur documentation avant de vous connecter directement.

​
Sécuriser votre webhook

Pour vérifier que les requêtes proviennent de OneSignal et n’ont pas été altérées :
  • Signature HMAC : Incluez un secret partagé dans la configuration du webhook. OneSignal signe chaque requête avec un en-tête HMAC que votre serveur peut valider avant de traiter la charge utile.
  • Token d’authentification personnalisé : Ajoutez un en-tête d’autorisation personnalisé (par exemple, Authorization: Bearer VOTRE_TOKEN_SECRET) et vérifiez-le côté serveur avant d’accepter la requête.

​
FAQ

​
Puis-je utiliser les webhooks pour appeler les API OneSignal ?

Non. Les webhooks de Journey sont conçus uniquement pour envoyer des données à des systèmes externes. Ils ne peuvent pas appeler les API OneSignal. Pour mettre à jour les données OneSignal en fonction des événements de Journey, routez le webhook via votre propre serveur et faites appeler l’API OneSignal par votre serveur.

​
Pourquoi mon webhook a-t-il été automatiquement désactivé ?

OneSignal désactive les webhooks qui échouent de manière constante pour éviter d’autres problèmes. Vérifiez l’onglet Journaux pour les détails des erreurs (codes de statut, corps de réponse), corrigez la cause principale et testez le webhook avant de le réactiver. Les causes courantes incluent les pannes d’endpoint, les erreurs d’authentification et la limitation de débit.

​
Comment puis-je dédupliquer les événements webhook ?

Utilisez la valeur event.id (disponible en en-tête ou dans le corps de la requête) pour identifier les événements uniques. Stockez les ID d’événements traités sur votre serveur et ignorez les doublons. C’est particulièrement important si les nouvelles tentatives livrent le même événement plusieurs fois.

​
OneSignal limite-t-il le débit des requêtes webhook ?

Non. OneSignal envoie les requêtes webhook immédiatement lorsque les utilisateurs atteignent l’étape, sans limitation de débit. Si de nombreux utilisateurs atteignent une étape webhook en même temps, votre endpoint reçoit une rafale de requêtes. Créez votre endpoint pour gérer le volume maximal, ou utilisez un proxy de mise en file d’attente pour mettre en mémoire tampon et regrouper les requêtes.

​
Puis-je tester les webhooks sans lancer un Journey ?

Oui. Utilisez le bouton Test dans la configuration du webhook pour envoyer une requête exemple. Notez que les tags ne sont pas disponibles dans les requêtes de test — utilisez des abonnements de test dans un Journey actif pour une validation complète.

​
Pages connexes

Vue d'ensemble des Journeys

Introduction aux Journeys et fonctionnement des flux multicanaux.

Actions de Journey

Ajoutez des étapes d’attente, une logique de branchement, des fenêtres de temps et des chemins divisés.

Syntaxe Liquid

Référence complète pour les templates Liquid dans les messages et webhooks OneSignal.

Personnalisation des messages

Vue d’ensemble de toutes les méthodes de personnalisation incluant les tags, Liquid et le contenu dynamique.