Webhook

Aide 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 des données client à des outils d’analyse
• Déclencher des e-mails, SMS ou WhatsApp tiers lors d’événements spécifiques du parcours

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

Ajouter 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.

Nommer l’étape Webhook et spécifier 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 le menu déroulant TYPE DE REQUÊTE : GET ou POST.

Note

L’URL doit être publiquement accessible. Pushwoosh rejette les adresses privées, internes, de bouclage et locales de lien, y compris les points de terminaison de métadonnées cloud, qu’elles proviennent de l’URL elle-même ou d’une redirection vers laquelle elle pointe. Voir Délai d’attente, nouvelles tentatives et requêtes échouées pour ce qui se passe lorsqu’une requête est bloquée.

Configurer 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é.

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 deux-points. Par exemple : <username>:<password>
2. Encodez cette chaîne en Base64.
3. Copiez la chaîne Base64 résultante (par exemple, <base64-encoded-string>).
4. Dans les paramètres du webhook, ajoutez un en-tête Authorization avec la valeur : Basic <base64-encoded-string>. Assurez-vous qu’il y a un espace après le mot « Basic ».

Marquer une valeur d’en-tête comme secrète

Cliquez sur l’icône en forme d’œil à côté de la valeur d’un en-tête pour la masquer. Pushwoosh cache cette valeur partout où elle quitterait autrement le service : dans l’interface utilisateur, dans les réponses de l’API et dans l’historique des versions du parcours.

• Masquage automatique. Les en-têtes dont les noms ressemblent à des informations d’identification sont masqués automatiquement, même si vous ne cliquez jamais sur l’icône en forme d’œil. Cela inclut Authorization, Proxy-Authorization, Cookie, Set-Cookie, et tout nom contenant token, secret, password, credential, auth, ou api-key/api_key/apikey (avec un trait d’union, un underscore, ou sans séparateur).
• Modifier une valeur masquée. Cliquez dans le champ affichant •••••••• et tapez la nouvelle valeur. Il n’y a pas de bouton pour révéler la valeur stockée. L’icône en forme d’œil reste verrouillée tant que le masque est affiché. Pour supprimer l’indicateur de secret d’un en-tête, tapez d’abord une nouvelle valeur, puis cliquez sur l’icône.
• Renommer un en-tête masqué. Renommer un en-tête dont la valeur est actuellement affichée comme le masque efface cette valeur. Saisissez-la à nouveau sous le nouveau nom. Renommer un en-tête qui contient actuellement une valeur que vous venez de taper conserve cette valeur.

Note

Dans l’historique des versions du parcours, une modification de la valeur d’un en-tête secret affiche le masque des deux côtés de la comparaison. Vous pouvez savoir qu’un en-tête secret a changé, mais pas de quoi à quoi il a changé.

Ajouter 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 le placeholder de Données dynamiques lorsque la requête est envoyée, Pushwoosh envoie une chaîne vide à sa place.

Exemple :

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

Utiliser les données dynamiques et les 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 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 avait 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.

Saisir manuellement des placeholders supplémentaires

Un placeholder est une macro que vous tapez à la main au lieu de la générer à partir d’une catégorie du CONSTRUCTEUR DE DONNÉES. Le panneau CONSTRUCTEUR DE DONNÉES ne couvre que les données d’Appareil, de Tag et d’Événement. Tapez ces placeholders directement dans les sections URL, EN-TÊTES ou DONNÉES. Ils n’apparaissent pas dans le panneau :

Placeholder	Valeur
{{application_code}}	Le code d’application de l’application à laquelle appartient le voyageur.
{{traveler:id}}	L’ID que Pushwoosh assigne à ce voyageur pour cette exécution de parcours.
{{journey:uuid}}	L’UUID de ce parcours.
{{journey:name}}	Le nom de ce parcours.
{{point:uuid}}	L’UUID de cette étape Webhook.
{{point:name}}	Le NOM DE L’ÉTAPE de cette étape Webhook.
{{event:name}}	Le nom de l’événement qui a déclenché l’entrée de ce voyageur dans le parcours.
{{device:platform}}	La plateforme de l’appareil, par exemple Android ou iOS.
{{device:push_subscribed}}	Si le voyageur est abonné aux notifications push — true ou false.
{{now}}	La date et l’heure actuelles, ISO 8601, UTC.
{{now:unix_ms}}	L’heure actuelle en millisecondes Unix.
{{tags:all}}	Chaque valeur de Tag pour l’appareil du voyageur, sous forme d’un seul objet JSON. Utilisez-le sans guillemets, par exemple "user_properties": {{tags:all}}. Le mettre entre guillemets transforme l’objet en une chaîne de caractères échappée.

Note

Un placeholder mal orthographié, ou qui n’est pas dans cette liste ou dans le CONSTRUCTEUR DE DONNÉES, est envoyé au point de terminaison exactement tel que tapé, accolades comprises. Il n’y a pas de bannière d’erreur pour cela. Vérifiez le corps de la requête dans le Journal des appels si une valeur que vous attendiez est manquante.

Conserver le type d’un placeholder dans le corps JSON

Un placeholder entre guillemets devient toujours une chaîne JSON, quel que soit le type réel de la valeur. Le même placeholder seul, sans guillemets autour, conserve le type propre de la valeur : un nombre reste un nombre, true/false reste un booléen, et une liste devient un tableau JSON. Un placeholder sans guillemets doit être la valeur entière du champ — "age": {{tag:Age}} fonctionne, mais "note": prefix{{tag:Age}}suffix ne fonctionne pas, car tout ce qui est en dehors des guillemets est écrit exactement tel que tapé et les caractères supplémentaires cassent le JSON.

{
  "age": {{tag:Age}},
  "age_as_text": "{{tag:Age}}"
}

Ici, age envoie la valeur numérique du Tag (34), tandis que age_as_text envoie la chaîne "34". Utilisez celui que le champ du côté récepteur attend. Si le Tag n’a pas de valeur, un placeholder sans guillemets se résout toujours en une chaîne vide, pas en un nombre ou false. Voir la note sous Ajouter le corps de la requête JSON.

Attention

Un placeholder de date est rendu différemment selon l’endroit où vous le placez. Entre guillemets, il conserve le format YYYY-MM-DD HH:MM:SS que les intégrations existantes analysent déjà. Sans guillemets, il est au format ISO 8601, par exemple 2026-09-15T08:24:00Z. Les deux ne sont pas interchangeables. Choisissez la position qui correspond au format attendu par votre point de terminaison.

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

En plus d’envoyer des données, l’étape Webhook peut conserver les valeurs de la réponse que votre service renvoie. Vous donnez un nom à chaque valeur (Attribut). Les étapes ultérieures peuvent utiliser ce nom de la même manière qu’elles utilisent d’autres valeurs de réponse de webhook. Par exemple, définissez un Tag avec Mettre à jour le profil utilisateur, ou programmez un Délai à partir d’une date renvoyée par le service. Pour un exemple de parcours complet, voir Utilisation des données de réponse de webhook dans votre parcours.

Exemple : le CRM renvoie un ID utilisateur. Vous le stockez comme Attribut crm_user_id. Ensuite, Mettre à jour le profil utilisateur l’écrit dans un Tag.

Avant de mapper quoi que ce soit, obtenez un exemple de réponse du service. Demandez à votre développeur, ou ouvrez un appel réussi dans le Journal des appels après un test et regardez le corps de la réponse. Vous avez besoin des noms de champs de cette réponse pour construire le Chemin.

Dans la section MAPPAGE DE LA 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 JSON de la réponse, avec des points entre les niveaux
• Attribut : le nom que vous utiliserez plus tard dans le parcours

Par exemple, si votre CRM répond avec :

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

1. Définissez le Chemin sur data.user.id.
2. Définissez l’Attribut sur crm_user_id.

Après qu’un utilisateur a passé cette étape, les éléments ultérieurs peuvent choisir l’Attribut crm_user_id de la même manière qu’ils choisissent d’autres valeurs de réponse de webhook.

Division par condition ne peut pas les utiliser directement. Les valeurs de webhook mappées n’ont pas de type. Enregistrez d’abord la valeur en tant que Tag, puis branchez sur ce Tag. Voir Comparer une valeur de webhook dans la Division par condition.

Attention

Si la réponse est supérieure à 64 Ko, aucune partie n’est mappée. Gardez la réponse que votre point de terminaison renvoie raisonnablement petite si vous prévoyez de mapper des valeurs à partir de celle-ci.

Pour un seul champ, le Chemin et les valeurs fonctionnent comme ceci :

Note

• Écrivez les noms d’objets avec des points : data.user.id.
• Pour une liste, utilisez un numéro de position pour prendre un élément. Le premier élément est 0, donc results.0.code est le champ code du premier élément. Pour mapper chaque élément d’une liste, voir Mapper chaque élément d’un tableau.
• Vous ne pouvez pas mapper seulement certains éléments d’une liste. Pour une liste, c’est soit une position, soit tous les éléments.
• Pushwoosh conserve la valeur telle que le service l’a envoyée (texte, nombre ou vrai/faux). Un nombre 100 reste un nombre. Le texte "100" reste du texte et ne fonctionnera pas là où le parcours attend un nombre. Pour une date de Délai, le service doit renvoyer un format que Délai accepte. Un décimal comme 19.99 peut aller dans un Tag de type Prix.
• Si la réponse n’est pas un JSON valide, ou si le Chemin ne correspond à aucun champ, cet attribut n’est pas créé pour cet utilisateur. L’étape Webhook se termine toujours normalement. Il n’y a pas de bannière d’erreur. Vérifiez le corps de la réponse dans le Journal des appels et corrigez le Chemin si la valeur est manquante en aval.

Mapper chaque élément d’un tableau

Parfois, une réponse de webhook n’a pas qu’une seule valeur. Elle a une liste, comme chaque produit d’une commande, chaque article d’un panier, ou chaque résultat d’une recherche. Le mappage de réponse capture normalement une valeur par champ, donc sans cela, vous n’obtiendriez qu’une seule valeur mappée de cette liste, et le reste serait perdu.

Mettez * dans le champ Chemin où se trouve la liste. Pushwoosh récupère alors une valeur de chaque élément de la liste, pas seulement d’une position. Par exemple, si la liste s’appelle items et que chaque élément a un item_name, définissez le Chemin sur items.*.item_name.

Dans MAPPAGE DE LA RÉPONSE, cliquez sur + AJOUTER UN MAPPAGE et remplissez les deux champs comme d’habitude, avec * marquant la liste :

• Chemin : l’emplacement de la valeur à l’intérieur de la réponse, avec * là où se trouve la liste. Exemple : items.*.item_name.
• Attribut : le nom que vous utiliserez plus tard. Ce que vous écrivez ici décide de la manière dont vous récupérez les résultats :
  • Incluez {n} dans le nom, par exemple item_{n}, pour obtenir chaque élément comme sa propre valeur, numérotée à partir de 1 : item_1, item_2, item_3, et ainsi de suite. {n} peut se trouver n’importe où dans le nom, par exemple item_{n}_sku.
  • Laissez {n} de côté, par exemple item_names, pour joindre chaque élément en une seule valeur, séparée par des virgules : Sofa, Lamp, Rug.

Les positions de la liste dans le chemin commencent à 0 (items.0.item_name est le premier élément). Les noms d’attributs construits avec {n} commencent à 1 (item_1 est ce premier élément). Ce sont deux numérotations différentes.

Si vous n’avez besoin que d’un seul élément de la liste, utilisez un nombre dans le Chemin au lieu de *, par exemple items.0.item_name.

Exemple

Si votre CRM répond avec :

{
  "items": [
    { "item_name": "Sofa" },
    { "item_name": "Lamp" },
    { "item_name": "Rug" }
  ]
}

• Définissez le Chemin sur items.*.item_name et l’Attribut sur item_{n} pour obtenir trois valeurs distinctes : item_1 est Sofa, item_2 est Lamp, item_3 est Rug.
• Définissez l’Attribut sur item_names à la place pour obtenir une seule valeur : item_names est Sofa, Lamp, Rug.

Note

Si un élément de la liste ne contient pas le champ que vous recherchez (par exemple, pas de item_name), cet élément est ignoré. La numérotation ne laisse pas de vide pour lui. Exemple : trois lignes où celle du milieu n’a pas de item_name deviennent item_1 et item_2 seulement.

Seuls les 50 premiers éléments d’une liste sont capturés. Tout ce qui dépasse est abandonné. Le voyageur continue toujours dans le parcours. Seules les valeurs non mappées sont manquantes.

Vous pouvez utiliser les valeurs mappées plus tard dans le parcours comme n’importe quel autre attribut de réponse de webhook :

• Mettre à jour le profil utilisateur : enregistrer une valeur dans un Tag
• Délai : attendre jusqu’à une date de la réponse
• Contenu dynamique : personnaliser le contenu du message

Division par condition ne peut pas les utiliser directement. Les valeurs de webhook mappées n’ont pas de type. Enregistrez d’abord la valeur en tant que Tag, puis branchez sur ce Tag. Voir Comparer une valeur de webhook dans la Division par condition.

Utilisation des données de réponse de webhook dans votre parcours

Délai d’attente, nouvelles 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.

Nouvelles tentatives

En cas de réponse 500, 502, 503 ou 504, ou d’une erreur réseau telle qu’un échec de connexion, Pushwoosh réessaie la requête une fois avant d’abandonner. Une requête qui expire n’est pas réessayée — voir Que se passe-t-il lorsqu’une requête échoue ci-dessous. Toute autre réponse non-2xx n’est pas non plus réessayée.

Note

Une nouvelle tentative renvoie exactement la même requête. Rendez votre point de terminaison sûr pour recevoir le même appel deux fois (idempotent) si un doublon poserait problème, par exemple facturer un paiement ou créer un enregistrement deux fois.

Limites de débit

Pushwoosh limite le nombre de requêtes webhook qu’un compte peut envoyer par seconde. La limite est dimensionnée bien au-dessus des pics de trafic réels, de sorte que les parcours normaux ne sont pas affectés. Une rafale qui la dépasse attend brièvement de la place avant d’échouer.

Période de refroidissement du point de terminaison

Si un point de terminaison échoue plusieurs fois de suite, Pushwoosh cesse de lui envoyer des requêtes pendant un certain temps au lieu de réessayer un point de terminaison défectueux sur chaque voyageur, en commençant par 30 secondes et en doublant lors d’échecs ultérieurs jusqu’à 5 minutes. Une seule requête réussie efface cela et reprend la livraison normale.

Que se passe-t-il lorsqu’une requête échoue

L’élément Webhook n’a pas de branche distincte pour les requêtes échouées. L’un des événements suivants fait sortir le voyageur du parcours à cette étape :

Cause	Ce qui le déclenche
Adresse de point de terminaison bloquée	L’URL est privée, interne, de bouclage ou locale de lien, y compris les points de terminaison de métadonnées cloud
Limite de débit	La limite de requêtes webhook par seconde du compte est dépassée et aucune place ne se libère pendant la brève attente
Période de refroidissement du point de terminaison	Le point de terminaison a échoué plusieurs fois de suite et Pushwoosh le saute temporairement
Délai d’attente	Aucune réponse dans les 10 secondes, ou l’étape dépasse son plafond de 30 secondes
Erreur réseau	La requête n’a pas pu atteindre le point de terminaison du tout
Réponse non-2xx	Le point de terminaison a renvoyé un statut d’erreur qui n’est pas réessayé, ou a été réessayé une fois et a de nouveau échoué

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 s’applique à chaque étape Webhook, y compris celles créées précédemment. Une adresse de point de terminaison qui correspond maintenant à la règle d’adresse bloquée ci-dessus commencera à échouer de la même manière.

Contrairement à une requête échouée, 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.

Tester le Webhook

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

Si un en-tête affiche toujours le masque stocké, Pushwoosh remplit la valeur réelle enregistrée pour la requête de test. La valeur n’apparaît jamais dans votre navigateur.

Cette substitution ne fonctionne que pour un en-tête déjà enregistré sur cette étape exacte. Une étape que vous n’avez pas encore enregistrée, ou une que vous venez de copier, n’a pas de valeur enregistrée derrière le masque, donc Pushwoosh envoie la requête de test sans cet en-tête.

Après un test réussi (ou un appel en direct), ouvrez le Journal des appels, développez la ligne et comparez le corps de la réponse avec chaque Chemin. Le champ doit exister exactement comme dans le Chemin. Si la requête réussit mais qu’une étape ultérieure n’a pas de valeur, le Chemin ne correspond généralement pas à la réponse. L’étape Webhook n’affichera pas d’erreur pour cela.

Enregistrer votre configuration

Cliquez sur Enregistrer pour sauvegarder votre configuration de webhook.

Journal des appels

Ouvrez l’onglet Journal des appels dans le tiroir du point pour voir ce que Pushwoosh a réellement envoyé pour cette étape : heure, utilisateur, résultat et durée, remontant à 30 jours.

Note

Le Journal des appels n’enregistre que les requêtes que Pushwoosh a réellement envoyées. Un voyageur abandonné avant ce point, par exemple par la limite de débit ou une période de refroidissement du point de terminaison, n’obtient pas de ligne ici.

Filtrez par résultat (Succès, Erreur HTTP, Pas de réponse) ou recherchez par l’ID utilisateur ou le HWID exact. Cliquez sur une ligne pour la développer et voir la requête (méthode, URL et corps) et, selon le résultat, soit la réponse (statut et corps), soit le texte de l’erreur. La Durée couvre l’ensemble de l’étape, y compris le temps passé sur une nouvelle tentative automatique.

Attention

Les corps de requête et de réponse de plus de 4 Ko sont coupés, marqués par …[tronqué]. Toute valeur que Pushwoosh a envoyée dans un en-tête, comme un jeton bearer ou une clé API, est remplacée par [expurgé] partout où elle apparaîtrait autrement : dans l’URL, les corps et le texte de l’erreur, pas seulement dans un champ d’en-têtes.