Webhook

Assistance d'un développeur requise

Vous aurez besoin de l’aide de votre équipe de développeurs pour configurer l’élément Webhook. Partagez ce guide avec eux pour commencer.

Les webhooks vous permettent d’envoyer des données de parcours à des services externes tels que des outils d’analyse, des systèmes CRM et des outils marketing. Vous pouvez :

• Notifier les systèmes externes lorsqu’un client effectue une action dans le parcours
• Envoyer les données client à des outils d’analyse
• Déclencher des e-mails, SMS ou WhatsApp tiers lors d’événements de parcours spécifiques

Note

Découvrez quelques exemples sur la manière d’implémenter des webhooks pour différents cas d’utilisation et services : Exemples d’intégration de Webhook

Comment configurer l’élément Webhook

Ajoutez l’élément Webhook

Faites glisser et déposez l’élément Webhook sur le canevas. Placez le Webhook où vous le souhaitez, en gardant à l’esprit les informations de parcours que vous allez envoyer à un service tiers.

Nommez l’étape Webhook et spécifiez l’URL et le type de la requête

Dans le champ NOM DE L’ÉTAPE, saisissez un nom pour le webhook. Il peut être pratique de nommer les webhooks en fonction des services auxquels ils envoient des données ou du cas d’utilisation.

Ensuite, dans le champ URL, spécifiez l’URL de la requête à laquelle les données doivent être envoyées. À côté du champ URL, sélectionnez le type de requête dans la liste déroulante TYPE DE REQUÊTE : GET ou POST.

Configurez les en-têtes

Dans la section EN-TÊTES, définissez le type de contenu.

Par défaut, le type de contenu est application/json. Si le service auquel vous envoyez le webhook nécessite un autre type de contenu, saisissez celui qui convient dans la valeur de l’en-tête Content-Type.

Exemples de types de contenu :

• x-www-form-urlencoded
• text/plain
• text/xml

Ajoutez des en-têtes supplémentaires si nécessaire en cliquant sur + AJOUTER UN EN-TÊTE. Vous pouvez supprimer n’importe quel en-tête en cliquant sur l’icône ‘x’ à côté de celui-ci.

Ajoutez l’en-tête d’authentification requis par votre point de terminaison, par exemple :

• Authorization: Bearer <token>
• X-Api-Key: <key>
• Authorization: Basic <base64(user:pass)>

Seul un secret statique dans un en-tête est pris en charge. Les flux d’échange de jetons OAuth2, mTLS et la signature de requêtes côté Pushwoosh ne sont pas pris en charge. Vous pouvez également restreindre le point de terminaison aux adresses IP de Pushwoosh au lieu de, ou en plus de, un secret d’en-tête. Voir Adresses IP de Pushwoosh.

Note

Besoin de passer une valeur par utilisateur, comme un jeton ou un ID, au lieu d’un secret fixe ? Insérez une macro de données dynamiques dans l’URL ou le corps JSON, par exemple comme paramètre de requête ou champ de corps que votre point de terminaison lit.

Pour l’authentification HTTP Basic spécifiquement, procédez comme suit :

1. Ouvrez un éditeur de texte brut et tapez votre nom d’utilisateur et votre mot de passe sans espaces, séparés par un deux-points. Par exemple : myuser:mypass
2. Encodez cette chaîne en Base64.
3. Copiez la chaîne Base64 résultante (par exemple, bXl1c2VyOm15cGFzcw==).
4. Dans les paramètres du webhook, ajoutez un en-tête Authorization avec la valeur : Basic <VOTRE CHAÎNE BASE64>. Assurez-vous qu’il y a un espace après le mot “Basic”.

Ajoutez le corps de la requête JSON

Dans la section DONNÉES, saisissez le corps de votre requête JSON. Assurez-vous que le corps de la requête est au format JSON correct.

Note

S’il n’y a pas de valeur pour l’espace réservé des données dynamiques lorsque la requête POST est envoyée, la valeur nulle sera transmise.

Exemple :

{
  "hwid": "{{device:hwid}}"
}

Utilisez des données dynamiques et des macros

Le panneau CONSTRUCTEUR DE DONNÉES vous permet d’insérer des informations dynamiques (telles que des données d’utilisateur, d’appareil, de Tag ou d’événement) directement dans le corps de votre requête JSON. Avec les données dynamiques, vous pouvez inclure des valeurs spécifiques à l’utilisateur individuel progressant dans le parcours.

Pour cela :

1. Sélectionnez une catégorie. Vous pouvez extraire des données de trois catégories :

   • Appareil : Utilisez les données de l’appareil lorsque vous avez besoin d’informations techniques liées à l’appareil de l’utilisateur.

   • Tag : Utilisez les données de Tag lorsque vous souhaitez envoyer des informations stockées dans le profil de l’utilisateur.

   • Événement : Utilisez les données d’événement lorsque le webhook doit envoyer des valeurs de l’événement déclencheur du parcours.

Note

Les valeurs de l’événement déclencheur restent attachées au voyageur pour le reste du parcours, y compris à travers un Délai. Elles ne sont perdues que si le voyageur quitte le parcours, par exemple lors d’un événement d’annulation, d’une sortie, ou lorsque le parcours se termine. Si un voyageur passe par la même étape Webhook plus d’une fois, la nouvelle réponse écrase la valeur qu’elle a mappée la dernière fois.

2. Sélectionnez un paramètre (par exemple, HWID, catégorie préférée, etc.).
3. Pushwoosh génère une macro qui ressemble à ceci :

{{tag:Language}}

4. Copiez la macro et collez-la dans votre corps JSON dans la section DONNÉES.

Lorsque le webhook s’exécute dans un parcours en direct, Pushwoosh remplace automatiquement la macro par la valeur réelle pour cet utilisateur.

Mappez les données de réponse du webhook à des variables

En plus d’envoyer des données, l’élément Webhook peut également capturer des données de la réponse qu’il reçoit et les transformer en variables. Ces variables peuvent ensuite être utilisées plus tard dans le parcours. Par exemple, définissez un Tag avec Mettre à jour le profil utilisateur, ou planifiez un Délai basé sur une valeur renvoyée par le service externe. Pour un exemple de parcours complet, voir Utiliser les données de réponse du webhook dans votre parcours.

Dans la section MAPPAGE DE RÉPONSE, cliquez sur + AJOUTER UN MAPPAGE et remplissez deux champs pour chaque valeur que vous souhaitez capturer :

• Chemin : l’emplacement de la valeur à l’intérieur du corps de la réponse JSON
• Attribut : le nom que vous utilisez pour référencer cette valeur plus tard dans le parcours

Par exemple, si votre CRM répond avec :

{
  "data": {
    "user": {
      "id": "789xyz"
    }
  }
}

Définissez Chemin sur data.user.id et Attribut sur crm_user_id pour capturer cet ID.

Note

Quelques points à savoir sur le mappage :

• Chemin est un chemin simple séparé par des points (clés d’objet et, pour les tableaux, des index numériques, par exemple results.0.code). Il ne prend pas en charge les jokers ou les filtres, il ne peut donc pointer que vers une seule valeur spécifique à la fois.
• Les valeurs sont stockées exactement comme elles proviennent de la réponse JSON (texte, nombre ou vrai/faux). Il n’y a pas de conversion de type : 100 est mappé comme un nombre, mais "100" est mappé comme du texte et ne fonctionnera pas dans une comparaison numérique. Si vous prévoyez d’utiliser une valeur comme date dans un élément Délai, assurez-vous que votre service la renvoie dans l’un des formats de date pris en charge par Délai. Un nombre décimal (par exemple 19.99) peut être enregistré dans un Tag de type Prix.
• Si la réponse n’est pas un JSON valide, ou si un Chemin ne correspond à rien, la variable correspondante n’est pas créée pour cet utilisateur. Aucune erreur n’est affichée, et l’étape Webhook se termine toujours normalement.

Attention

Les corps de réponse de plus de 64 Ko ne sont pas du tout traités pour le mappage. Gardez la réponse que votre point de terminaison renvoie raisonnablement petite si vous prévoyez de mapper des valeurs à partir de celle-ci.

Utiliser les données de réponse du webhook dans votre parcours

Délai d’attente, tentatives et requêtes échouées

Pushwoosh attend jusqu’à 10 secondes pour une réponse. L’ensemble de l’étape Webhook, y compris l’envoi de la requête et le traitement de la réponse, est plafonné à 30 secondes. Chaque voyageur déclenche la requête une fois, et il n’y a pas de tentatives automatiques.

Attention

Un délai d’attente, une erreur réseau ou une réponse non-2xx fait sortir le voyageur du parcours à cette étape, car l’élément Webhook n’a pas de branche séparée pour acheminer les requêtes échouées. Voir Erreur de requête. Si vous ne pouvez pas vous permettre de perdre des voyageurs ici, faites en sorte que votre point de terminaison renvoie toujours une réponse 2xx et mettez tout état d’échec dans le corps de la réponse à la place, par exemple comme une valeur que votre Mappage de réponse peut récupérer.

Cela ne couvre que l’échec de la requête elle-même. Une réponse qui arrive mais ne se mappe pas correctement, comme un JSON invalide, un Chemin non résolu, ou un corps de plus de 64 Ko, ne fait pas sortir le voyageur. Voir la note sous Mappage de réponse ci-dessus.

Testez le Webhook

Cliquez sur Tester le webhook pour vérifier que la configuration de votre webhook est correcte et que la requête est envoyée avec succès.

Enregistrez votre configuration

Cliquez sur Appliquer pour enregistrer la configuration de votre webhook.