Important : Veuillez noter que le nœud Webhook est une fonctionnalité avancée, ce qui signifie que vous devez disposer de certaines ressources techniques pour l'intégrer à votre (vos) application(s) et qu'il est de votre responsabilité de vous assurer que le service intégré fonctionne correctement.
Vous pouvez créer des configurations webhook à utiliser dans vos programmes Automation avec le noeud Webhook. Ce noeud vous permet d'établir la communication entre Emarsys et d'autres solutions d'expérience client. En utilisant des webhooks, vous pouvez envoyer des données à votre système ou votre application externe quand un contact arrive au noeud Webhook au sein d'un parcours Interactions ou Automation Center.
Pages liées :
Pré-requis
- Seuls les utilisateurs possédant des autorisations Autorisations d'éditeur de préréglages de noeud Webhook peuvent créer, modifier ou supprimer des préréglages de noeud Webhook. Si de telles actions vous sont impossibles, veuillez contacter votre responsable du compte. Vous pouvez consulter les autorisations utilisateur sur la page Gestion > Gestion d'utilisateur.
- Vous devez avoir un système ou une solution externe prête à recevoir l'événement envoyé par Emarsys (nous envoyons les événements via des requêtes POST API). Les événements sont envoyés au format JSON, la structure de contact et les données supplémentaires constituant un niveau unique. De manière facultative, vous pouvez aussi envoyer des attributs de données événementielles qui sont répertoriés sous l'objet
event_data(c'est-à-dire au deuxième niveau de la hiérarchie). Par exemple :
{ "event_time": "2021-04-01T17:08:44Z", "email_address": "example@emarsys.com" "event_data": { "event_time": "2021-04-01T17:05:11Z", "order_id": 4534322, "Order_status": "shipped" }, "scenario": "shipping_update" }- Condition préalable facultative, si vos mesures de sécurité exigent l'utilisation d'une liste d'autorisations : Le nœud Webhook se connectera à votre solution d'expérience client en utilisant des adresses IP spécifiques. Pour permettre à ce nœud de communiquer avec votre solution, vous devez ajouter les adresses IP suivantes à votre liste d'autorisations :
- 34.89.173.3
- 35.246.249.205
- 34.89.137.140
Cas d'usage
Connecter Emarsys à des canaux hors-ligne.
Si vous souhaitez connecter Emarsys à vos canaux hors-ligne (par ex. les centres de distribution où vous ajoutez des cadeaux personnalisés aux colis et organisez vos solutions de publipostage), alors le noeud Webhook peut être pratique.
Créer un préréglage de noeud Webhook
Voici ce que vous devez faire pour créer un préréglage de noeud Webhook :
1. Naviguez jusqu'à Automation > Préréglages de noeud Webhook et cliquez sur Créer un préréglage.
2. Configurez l'Apparence de votre noeud Webhook :
a. Saisissez le nom du préréglage.
b. Sélectionnez un icône de noeud. L'icône noeud d'API est utilisée par défaut.
Après avoir sélectionné le préréglage dans le parcours, vous pouvez voir à quoi ressemble votre noeud dans l' Aperçu de noeud.
3. Configurez la Connexion.
Veuillez noter que vous ne pouvez pas créer de connexions aux endpoints api.emarsys.net avec le noeud Webhook.
a. Specifiez l' URL d'API endpoint de votre service ou application externe.
Notes :
- Vous devez spécifier une URL sécurisée, commençant par le préfixe
https://. - Veuillez ne pas utiliser d'URL dirigées vers un endpoint Emarsys quelconque.
- Si la requête échoue, le programme tente automatiquement de se reconnecter plusieurs fois et l'intervalle entre chaque tentative augmente de manière exponentielle de 30 secondes à 10 minutes. Après la 11e tentative infructueuse, le programme passe en mode Fail-safe. Par ailleurs, si vous souhaitez éviter que le programme ne soit mis en Fail-safe en cas d'erreurs mineures, assurez-vous que erreur 406 est renvoyé. Par conséquent, les contacts seront supprimés, mais le programme continuera à fonctionner.
b. Sélectionnez la Méthode d'authentification. Les méthodes suivantes sont disponibles :
- Authentification HTTP basique - Si vous sélectionnez cette méthode vous devez spécifier votre Nom d'utilisateur et votre Mot de passe.
- Authentification JWT - Si vous sélectionnez cette méthode vous devez spécifier votre Clé secrète.
- OAuth2 - Si vous sélectionnez cette méthode vous devez spécifier l' URL d'authentification, l' ID client, le Secret client et son Périmètre (facultatif).
4. Définir les données utiles de l'événement. La charge utile du noeud Webhook peut contenir des données d'événement déclencheur, des valeurs de champ de données de contact et des données supplémentaires avec des valeurs statiques.
a. Envoyer des données d'événement déclencheur - Cochez cette case si vous souhaitez transférer la charge utile de l'événement qui déclenche le programme.
Notes :
- Les attributs de données événementielles sont répertoriés sous l'objet
event_data. - Veuillez noter que le mapping de champ de données événementielles n'est pas disponible.
- Les données événementielles ne contiennent pas de metadata et incluent seulement les attributs disponibles dans le noeud Décision dans Interactions pour le filtrage des attributs. Cela signifie que les données de l'événement contenant les mêmes attributs seront envoyées au point de terminaison configuré (qui a déclenché le programme sans aucune donnée supplémentaire, quels que soient les nœuds traversés par l'événement déclencheur).
- Si vous cochez Envoyer des données d'événement déclencheur et utilisez ce préréglage dans un programme sans aucune charge utile événementielle (par ex. si l'événement extérieur ayant déclenché le programme ne contient aucune charge utile ou bien dans des programmes Automation Center récurrent), alors l'objet
event_datasera vide.
b. Données de contact - Ici vous pouvez définir des couples de valeurs clé pour envoyer des valeurs de champ de données de contact :
- Pour ajouter un nouveau champ, cliquez sur + Ajouter un champ.
- Pour supprimer un couple de valeurs clés, cliquez sur l'icône Supprimer.
Notes :
- Vous devez sélectionner au moins un champ de base de données de contact pour créer une configuration valide.
- Seuls les champs personnalisés et de système Emarsys peuvent être sélectionnés sous Données de contact.
Vous pouvez ajouter plusieurs champs supplémentaires à la charge utile. Ceux-ci sont au même niveau hiérarchique que les champs de contact.
Ici vous pouvez définir les éléments suivants :
- Nom du champ - Le nom de champ/clé qui apparaît dans la charge utile.
- Type de champ - Vous pouvez choisir parmi les types suivants : texte, numérique ou booléen.
- Valeurs prédéfinies - L'ajout de valeurs à un champ est facultatif. Après avoir saisi une valeur, cliquez sur Ajouter. Vous pouvez choisir parmi les options suivantes :
- Si vous ne saisissez pas de valeur prédéfinie, alors un champ de saisie sera disponible dans le noeud quand le préréglage sera sélectionné dans un parcours où les utilisateurs peuvent saisir toute valeur du type sélectionné.
- Si vous ne spécifiez qu'une seule valeur, alors la charge utile contiendra toujours cette valeur, mais les utilisateurs ne peuvent pas la modifier dans le noeud Webhook à l'intérieur du parcours Automation (c'est utile si vous souhaitez envoyer des ID système au système externe afin d'identifier l'origine de la requête).
- Si vous ajoutez plusieurs valeurs prédéfinies, alors les utilisateurs peuvent choisir la valeur depuis le menu déroulant dans le noeud Webhook qui sera envoyé dans la charge utile.
Dans ce cas, les marketeurs verront les options suivantes dans le noeud Webhook :
Pour s'assurer que le système récepteur ne traite pas les messages en double, nous recommandons d'utiliser le champ deduplication_ID .
Vous pouvez choisir parmi les champs suivants :
- deduplication_id - UUID utilisé pour éviter le traitement des messages en double.
- ems_program_id - L'ID du programme dans lequel le nœud Webhook a été déclenché.
- event_time - Horodatage indiquant le moment où le nœud Webhook a été déclenché.
5. Pour tester la connexion et l'authentification, et prévisualiser les données envoyées par le programme, cliquez sur Démarrer le test.
Si vous souhaitez tester comment votre programme va envoyer les données événementielles, créez un programme déclenché par l'événement spécifique.
Ici vous pouvez :
- Prévisualiser les données - Pour prévisualiser les données, saisissez l'adresse email du contact et cliquez sur Prévisualiser les données.
Notes :
- Vous pouvez prévisualiser les données et tester la connexion sans enregistrer le préréglage. C'est utile quand le préréglage est déjà utilisé dans des programmes actifs et que vous souhaitez tester les mises à jour avant de finaliser les changement.
- Le champ event_data contient un objet vide parce son contenu dépend fortement du programme où le noeud est utilisé. Si vous souhaitez tester la requête avec la charge utile de l'événement, nous recommandons de tester le programme.
- Une valeur aléatoire conforme au type sélectionné est générée pour les champs suivants :
deduplication_idems_program_idadditional data
- Tester la connexion - Vous pouvez ensuite tester la connexion en déclenchant votre endpoint avec les données d'aperçu. Cette option n'est possible qu'après avoir prévisualisé les données. Pour plus d'informations sur les codes d'état, voir Codes de réponse. Ici vous pouvez voir ce qui suit :
- Statut : Le code de réponse reçu de l'endpoint.
- Réponse : Le corps de la réponse.
- Aperçu de données : La charge utile envoyée à l'endpoint (qui est affichée à l'étape Prévisualiser les données).
Utiliser le noeud Webhook dans un programme Automation
1. Ouvrez le programme où vous souhaitez utiliser le noeud Webhook et insérez-le.
2. Double-cliquez sur le noeud Webhook et sélectionnez le préréglage de configuration requis dans le menu déroulant. Après avoir sélectionné le préréglage de configuration, l'icône et le nom de noeud changent en conséquence.
3. Ici vous verrez toutes les données configurées dans le préréglage sélectionné :
Notes :
- Si vous souhaitez ajouter ou retirer un champ, vous devez modifier le préréglage. Veuillez noter que vous devez avoir les autorisations
???pour modifier les préréglages de noeud Webhook. Si vous ne pouvez pas modifier des préréglages, veuillez contacter votre responsable du compte. - Vous ne pouvez pas modifier les préréglages utilisés dans des programmes actifs ou terminés. Dans ces cas-là, vous devez mettre les programmes en pause ou les geler pour modifier le préréglage.
- Données d'événement - Ici vous pouvez voir l'état des données événementielles. Les états suivantes sont disponibles :
- N'envoyer aucune donnée de l'événement déclencheur - Le programme n'envoie pas de données d'événement déclencheur.
- Des données de l'événement déclencheur sont envoyées - Des données d'événement déclencheur sont envoyées par le programme.
- Données de contact - La liste de couples de valeurs clés qui sont envoyés avec les valeurs de champ de données de contact sélectionnées.
- Données supplémentaires - Vous devez sélectionner ou saisir les valeurs statiques qui seront envoyées pour chaque contact traité.
Voici à quoi ressemble un noeud Webhook :
Gérer des préréglages de noeud Webhook
Vos préréglages de noeud Webhook sont répertoriés sur la page Automation > Préréglage de noeud Webhook.
Codes de réponse
Un échec de livraison peut mettre les programmes en mode fail-safe ou exclure des contacts des programmes. Les contacts qui ont quitté le programme au niveau du nœud Webhook sont comptabilisés comme Sortis sur la page Rapport de programme.
| Codes de réponse | Marqué comme reçu | Résultat |
|---|---|---|
| 20x (succès) | Oui | L'application a reçu les données envoyées par le noeud Webhook. |
| 30x (redirection) | Non | Les demandes qui échouent sont relancées et un programme est mis en Fail-safe après la 11e tentative infructueuse. Emarsys ne suivra pas la redirection. |
| 406 (pas acceptable) | Non | Le contact sortira du programme. |
| 408 (request timeout) | Non | Les demandes qui échouent sont relancées et un programme est mis en sécurité après la 11e tentative infructueuse. |
| 429 (rate limited) | Non | Les demandes qui échouent sont relancées et un programme est mis en sécurité après la 11e tentative infructueuse. |
| Autre 4xx (erreur client) | Non | Les demandes qui échouent sont relancées et un programme est mis en sécurité après la 11e tentative infructueuse. |
| 5xx (erreur serveur) | Non | Les demandes qui échouent sont relancées et un programme est mis en sécurité après la 11e tentative infructueuse. |
Problèmes et limitations connus
- Les demandes envoyées par le nœud Webhook expirent au bout de 20 secondes, ce qui signifie que si le point d'accès externe ne répond pas dans ce délai, la demande échoue.
- Le noeud Webhook envoie les requêtes une par une (et pas groupées). Par exemple, si vous souhaitez envoyer 1000 événements, alors une requête contiendra 1 événement ou contact à la fois.
- Avant d'envoyer des événements concernant un grand nombre de contacts, veuillez prendre en considération que cela pourrait prendre du temps (par ex. si vous utilisez le noeud Webhook dans un programme Automation Center où vous avez une liste de contacts comptant 100 000 contacts, alors 1 requête sera envoyée pour chaque contact et les contacts pourront poursuivre leur parcours après que toutes les réponses auront été reçues pour chaque contact de la part de votre système externe).
- Veuillez vous assurer que votre système externe est soigneusement préparer à recevoir un grand nombre d'événements (de sorte à ce que le système puisse gérer la charge et que cette dernière ne soit pas considérée comme une attaque DDoS).
- Si vous ajoutez le noeud Webhook à des programmes Interactions, veuillez prendre en compte qu'Emarsys ne peut pas garantir que l'engagement de service (SLA) Interactions est rempli de manière conséquente, parce que nous devons attendre la réponse de votre système externe après l'envoi de chaque événement.