Intégration des webhooks entrants

Les webhooks entrants permettent aux services tiers d’envoyer des événements directement à Pushwoosh. Lorsqu’un service tiers déclenche un webhook, Pushwoosh authentifie la requête, identifie l’utilisateur et applique le mappage que vous avez configuré : remplir les tags sur le profil de l’utilisateur, déclencher un événement Pushwoosh, ou les deux. Un événement déclenché peut alors démarrer ou faire avancer un Journey.

Utilisez les webhooks entrants pour connecter des outils comme des CRM, des plateformes d’e-commerce ou des services d’analyse sans avoir à construire ou à maintenir votre propre serveur.

Si l’identifiant entrant ne correspond à aucun utilisateur existant, Pushwoosh peut créer l’utilisateur au lieu de rejeter la requête. Activez la case à cocher de création automatique décrite dans Mapper les données entrantes.

Avant de commencer

Préparez les éléments suivants avant d’ouvrir la configuration du webhook.

Décidez de ce que le webhook doit faire. Un webhook doit mapper au moins un tag, un événement, ou les deux. Pour déclencher un événement, choisissez-en un existant dans votre projet (par exemple, CheckoutSuccess) ou créez-en un avec les attributs que vous souhaitez remplir à partir des données entrantes. Les tags peuvent être mappés à des tags existants ou créés sur-le-champ lors de la configuration du webhook.
Assurez-vous que votre service tiers peut envoyer des webhooks. Le service doit être capable d’envoyer une requête HTTP POST à une URL externe lorsque l’événement qui vous intéresse se produit, par exemple une nouvelle commande ou la soumission d’un formulaire.
Obtenez un exemple de charge utile (payload) JSON de votre service tiers. Il s’agit d’un petit exemple des données que le service envoie à chaque événement. Vous en aurez besoin pour mapper les champs de la charge utile aux tags et aux attributs d’événement.

Créer un webhook

Ouvrir la configuration du webhook

Dans votre compte Pushwoosh, allez dans Paramètres → Intégrations → Webhooks entrants et cliquez sur Paramètres.

Cliquez sur Créer un webhook pour ouvrir l’écran de configuration : Coller un exemple de charge utile à gauche, Configuration du webhook à droite.

Écran vide Créer un webhook avec l'éditeur de charge utile à gauche et le panneau de configuration du webhook vierge à droite

Saisissez un nom de webhook pour pouvoir l’identifier plus tard dans la liste.

Mapper les données entrantes

Dans Coller un exemple de charge utile, collez un exemple de charge utile JSON de votre service tiers. Pushwoosh extrait les champs et les charge dans les listes déroulantes des champs de la charge utile.

Exemple de charge utile :

{
  "id": "12345",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "loyalty_tier": "gold",
  "order_number": "ORD-001",
  "price": 99.99
}

Dans Identifier les utilisateurs par, choisissez comment Pushwoosh doit faire correspondre la requête entrante à un utilisateur :

ID utilisateur : votre identifiant interne attribué à un utilisateur dans le système.
E-mail : correspondance par adresse e-mail.
Téléphone : correspondance par numéro de téléphone.
HWID : un identifiant d’appareil, de navigateur ou d’e-mail.
Jeton (Token) : correspondance par un jeton push d’appareil.

Dans Champ de la charge utile, sélectionnez le champ qui contient la valeur correspondante.

Liste déroulante Identifier les utilisateurs par, sélecteur de champ de la charge utile et case à cocher Créer un nouvel ID utilisateur si aucune correspondance n'est trouvée

Optionnel : activez la case à cocher sous Champ de la charge utile pour créer automatiquement un nouvel utilisateur si aucune correspondance n’est trouvée, au lieu de rejeter la requête. Son libellé correspond à votre choix d’identifiant, par exemple Créer un nouvel ID utilisateur si aucune correspondance n’est trouvée ou Créer un nouvel E-mail si aucune correspondance n’est trouvée. La case à cocher est désactivée pour HWID et Jeton (Token), car Pushwoosh ne peut pas créer un identifiant d’appareil, de navigateur ou de jeton push avant une session SDK réelle.

Chaque webhook doit mapper au moins un tag, déclencher un événement, ou les deux.

Ajouter des tags au profil

Utilisez Ajouter des tags au profil pour enregistrer les valeurs de la charge utile en tant que tags sur le profil de l’utilisateur correspondant. Remplissez les données de profil comme le niveau de forfait ou la ville pour une meilleure segmentation.

Cliquez sur + Ajouter un tag.
Dans Nom du tag, choisissez un tag existant dans la liste, ou saisissez un nouveau nom. Pushwoosh affiche Créer : <nom> pour confirmer qu’il en créera un.
Si vous avez choisi un tag existant, Type affiche son type et ne peut pas être modifié. Si vous avez créé un nouveau tag, ouvrez Type et choisissez son type de données. Pushwoosh l’enregistre comme un tag spécifique à l’utilisateur de ce type.
Dans Champ de la charge utile, sélectionnez le champ de votre exemple de charge utile qui contient la valeur.
Répétez les étapes 1 à 4 pour chaque tag que vous souhaitez remplir.

Pour supprimer une ligne, cliquez sur ×.

Section Ajouter des tags au profil avec les mappages de lignes Nom du tag, Type et Champ de la charge utile de loyalty_tier à un tag de chaîne de caractères « Niveau de fidélité »

Enregistrer un événement

Utilisez Enregistrer un événement pour déclencher un événement Pushwoosh lorsque le webhook reçoit une requête valide. Un événement déclenché peut démarrer ou faire avancer un Journey.

Dans Événement, sélectionnez l’événement Pushwoosh à déclencher.
Cliquez sur + Ajouter un attribut.
Dans Attribut d’événement, choisissez un attribut existant de l’événement sélectionné dans la liste, ou saisissez un nouveau nom. Pushwoosh affiche Créer : <nom> pour confirmer qu’il en créera un.
Si vous avez choisi un attribut existant, Type affiche son type et ne peut pas être modifié. Si vous avez créé un nouvel attribut, ouvrez Type et choisissez son type de données.
Dans Champ de la charge utile, sélectionnez le champ de votre exemple de charge utile qui contient la valeur.
Répétez les étapes 2 à 5 pour chaque attribut que vous souhaitez remplir.

Pour supprimer une ligne, cliquez sur ×.

Section Enregistrer un événement avec l'événement CheckoutSuccess sélectionné et une ligne d'attribut d'événement mappant total (type Prix) à price

Activer et connecter

Lorsque la configuration est terminée, cliquez sur Activer le webhook. La fenêtre URL du webhook s’ouvre.

Copiez l’URL et définissez-la comme destination du webhook dans votre service tiers.
Copiez le Secret et collez-le dans votre service tiers comme valeur de l’en-tête Authorization. La valeur inclut le préfixe Bearer, utilisez-la donc telle quelle. Pushwoosh rejette toute requête où cet en-tête est manquant ou ne correspond pas.

Fenêtre URL du webhook montrant les champs URL et Secret avec des boutons de copie pour la configuration du service tiers

Cliquez sur Copier dans le bloc Exemple de requête pour copier un exemple de requête POST. Utilisez-le pour envoyer une requête de test et confirmer que Pushwoosh accepte le webhook, ou partagez-le avec votre équipe comme modèle pour l’intégration.

Fenêtre URL du webhook avec la commande curl URL, Secret et Exemple de requête pour la configuration du service tiers

Après avoir activé le webhook, il apparaît dans la liste des Webhooks avec un statut activé et commence à accepter les requêtes.

Liste des webhooks

La liste des webhooks entrants affiche chaque webhook de votre projet.

Chaque ligne affiche :

Nom : nom du webhook.
Statut : Activé ou Désactivé.
Reçus : nombre total de requêtes entrantes reçues par le webhook.
Dernière modification : date de la dernière modification du webhook.

Liste des webhooks entrants avec recherche, filtres de statut et colonnes Nom Statut Reçus Dernière modification

Gérer les webhooks

Ouvrez le menu de la ligne pour :

Modifier les paramètres : ouvre la configuration du webhook pour que vous puissiez changer le nom, l’événement, le mappage des champs et l’identification de l’utilisateur.
Copier l’URL : ouvre la fenêtre URL du webhook avec l’URL et le Secret pour que vous puissiez les copier à nouveau.
Journal d’activité : ouvre le journal des requêtes pour ce webhook.
Supprimer : supprime le webhook de la liste.

Pour un webhook activé, cliquez sur Désactiver pour le désactiver sans supprimer la configuration. Pour un webhook désactivé, cliquez sur Activer pour recommencer à accepter les requêtes.

Consulter le journal d’activité

Le journal d’activité affiche toutes les requêtes entrantes pour le webhook sélectionné.

Panneau de résumé

En haut, examinez le résumé des dernières 24 heures :

Total de requêtes : nombre total de requêtes entrantes reçues.
Avertissement : requêtes où l’utilisateur a été identifié (ou créé) mais où au moins un mappage de tag ou d’événement configuré n’a pas pu être appliqué.
Échouées : requêtes qui n’ont pas été traitées du tout, par exemple à cause d’un mauvais secret ou d’un champ d’identification manquant. Une requête échouée n’arrête pas le webhook. Pushwoosh continue d’accepter et de traiter les requêtes ultérieures.

Raison de l’échec	Signification
Authentification rejetée	Le secret partagé ne correspond pas à la configuration du webhook. Si cinq requêtes consécutives échouent avec cette erreur, Pushwoosh vous envoie une notification. Mettez à jour le secret pour reprendre. Aucune réactivation n’est nécessaire.
Champ d’identification de l’utilisateur manquant	Le champ de la charge utile mappé pour l’identification de l’utilisateur n’est pas présent dans la requête.

Journal d'activité avec le résumé Total de requêtes, Avertissement, Échouées et une entrée de requête montrant les coches ID utilisateur, Tags et Événement avec la charge utile JSON

Entrées de requête

Chaque entrée affiche une icône de statut, l’identifiant de l’utilisateur (par exemple, ID utilisateur ou E-mail), l’horodatage de la requête, et une coche pour chaque capacité que vous avez configurée sur le webhook : ID utilisateur (ou votre identifiant choisi), Tags et Événement. Une coche signifie que cette partie de la requête a été appliquée avec succès ; une requête peut afficher un mélange d’éléments cochés et échoués. Cliquez sur Afficher pour développer la charge utile JSON complète reçue.

Entrée de requête du journal d'activité avec l'identifiant de l'utilisateur, l'horodatage, les coches ID utilisateur, Tags et Événement, la charge utile JSON et le bouton Masquer

Consulter les événements et les tags déclenchés par webhook dans l’User Explorer

Lorsqu’une requête de webhook est traitée avec succès, Pushwoosh enregistre le résultat sur l’utilisateur correspondant (ou nouvellement créé) dans l’User Explorer. L’endroit où l’événement apparaît dépend de la manière dont vous avez identifié l’utilisateur :

ID utilisateur, E-mail ou Téléphone : l’événement est enregistré sur le profil de l’utilisateur. Ouvrez l’utilisateur et allez dans Historique des événements.
HWID : l’événement est enregistré sur l’appareil correspondant. Ouvrez l’utilisateur, trouvez l’appareil dans Appareils utilisateur actifs, et allez à son onglet Historique des événements.

Trouvez l’événement par son nom et développez-le pour voir les attributs mappés (par exemple, price ou products) et l’attribut __webhook avec l’ID du webhook. Les tags mappés apparaissent sur le même utilisateur, dans l’onglet Aperçu de l’utilisateur, quel que soit le type d’identifiant.

Onglet Historique des événements de l'User Explorer montrant un événement de webhook entrant avec les attributs développés, y compris l'ID __webhook et les champs de la charge utile mappés

Utiliser les webhooks entrants avec les Journeys

Une fois qu’un webhook est activé et déclenche des événements avec succès, utilisez l’événement sélectionné comme une entrée de Journey basée sur un déclencheur. Lorsque le webhook reçoit une requête valide, Pushwoosh déclenche l’événement mappé. Tout Journey qui utilise cet événement comme déclencheur d’entrée démarre automatiquement pour l’utilisateur correspondant.