Créer une campagne webhook

La création d’une campagne webhook ou l’inclusion d’un webhook dans une campagne multicanale vous permet de déclencher des actions hors application en fournissant à d’autres systèmes et applications des informations en temps réel.

Vous pouvez utiliser les webhooks pour envoyer des informations à des systèmes tels que Salesforce ou Marketo, ou à vos systèmes backend. Par exemple, vous pourriez vouloir créditer les comptes de vos clients d’une promotion après qu’ils ont effectué un événement personnalisé un certain nombre de fois.

Conseil

Pour en savoir plus sur les webhooks et comment les utiliser dans Braze, consultez Webhooks avant de continuer.

Étape 1 : Choisissez où créer votre message

Vous ne savez pas si votre message doit être envoyé via une Campaign ou un Canvas ? Les Campaigns conviennent mieux aux campagnes de communication ciblées et ponctuelles, tandis que les Canvas sont plus adaptés aux parcours utilisateurs en plusieurs étapes.

• campaign
• canvas

Étapes :

1. Allez dans Envoi de messages > Campagnes et sélectionnez Créer une campagne.
2. Sélectionnez Webhook ou, pour les Campaigns ciblant plusieurs canaux, sélectionnez Multicanal.
3. Donnez à votre Campaign un nom clair et explicite.
4. (Facultatif) Ajoutez une description pour expliquer comment cette Campaign sera utilisée.
5. Ajoutez des Teams et des tags si nécessaire.
   • Les tags facilitent la recherche de vos Campaigns et la création de rapports. Par exemple, lorsque vous utilisez le générateur de rapports, vous pouvez filtrer par tags spécifiques.
6. Ajoutez et nommez autant de variantes que nécessaire pour votre Campaign. Vous pouvez choisir des modèles de webhook différents pour chacune des variantes ajoutées. Pour en savoir plus à ce sujet, consultez Tests multivariés et A/B.

Conseil

Si tous les messages de votre Campaign sont similaires ou ont le même contenu, rédigez votre message avant d’ajouter d’autres variantes. Vous pourrez ensuite choisir Copier depuis la variante dans le menu déroulant Ajouter une variante.

Étapes :

1. Créez votre Canvas à l’aide du compositeur Canvas.
2. Après avoir configuré votre Canvas, ajoutez une étape dans le générateur Canvas. Donnez à votre étape un nom clair et significatif.
3. Choisissez une planification d’étape et spécifiez un délai si nécessaire.
4. Filtrez votre audience pour cette étape si nécessaire. Vous pouvez affiner davantage les destinataires de cette étape en spécifiant des segments et en ajoutant des filtres supplémentaires. Les options d’audience seront vérifiées après le délai, au moment de l’envoi des messages.
5. Choisissez votre comportement d’avancement.
6. Choisissez tout autre canal de communication que vous souhaitez associer à votre message.

Étape 2 : Créer votre webhook

Vous pouvez créer un nouveau webhook, partir d’un modèle existant ou utiliser l’un de nos modèles prêts à l’emploi. Ensuite, créez votre webhook dans l’onglet Composer de l’éditeur.

L’onglet Composer contient les champs suivants :

• Langues
• URL du webhook
• Méthode HTTP
• Corps de la requête

Langues

Vous pouvez envoyer un seul webhook à des utilisateurs répartis sur plusieurs marchés grâce aux messages multilingues. La traduction est prise en charge dans le corps de la requête et dans l’URL du webhook.

Pour localiser un webhook :

1. Créez les langues que vous souhaitez prendre en charge dans votre espace de travail.
2. Dans l’onglet Composer, entourez uniquement le texte à traduire avec des étiquettes de traduction. Par exemple : {% translation greeting %}Hello!{% endtranslation %}.
3. Sélectionnez Gérer les langues, choisissez vos langues, puis ajoutez les traductions en téléversant un fichier CSV ou en utilisant l’API de traductions.
4. Sélectionnez Utilisateur multilingue dans la liste déroulante Prévisualiser en tant qu’utilisateur pour prévisualiser chaque langue avant l’envoi.

Important

Entourez uniquement les valeurs lisibles par un humain avec des étiquettes de traduction. Jamais les clés JSON, les crochets, les virgules ou tout autre élément de structure. Les traducteurs peuvent modifier ou supprimer des caractères spéciaux, ce qui risque de produire un corps de requête mal formé que votre endpoint rejettera.

Pour un corps de requête composé de paires clé-valeur JSON, n’étiquetez que la valeur :

1
2
3

{
  "message_body": "{% translation order_ready %}Your order just arrived!{% endtranslation %}"
}

Localiser l’URL

Si votre endpoint varie selon le marché, vous pouvez entourer une partie de l’URL avec des étiquettes de traduction. Laissez le protocole (https://) en dehors des étiquettes et n’y incluez pas de paramètres de requête. Pour plus de détails, consultez Localiser les URL.

Modèles de webhook

Les modèles de webhook prennent en charge les traductions enregistrées : vous pouvez donc localiser un modèle une seule fois et le réutiliser dans vos Campaigns et vos étapes du Canvas. Vous devez disposer de l’autorisation Modifier les modèles de webhook pour ajouter des langues et des traductions à un modèle. Consultez la section Modèles de webhook.

URL du webhook

L’URL du webhook, ou URL HTTP, indique votre endpoint. L’endpoint est l’emplacement vers lequel vous envoyez les informations capturées dans le webhook.

Si vous souhaitez envoyer des informations à un fournisseur, celui-ci devrait indiquer cette URL dans sa documentation API. Si vous envoyez des informations vers vos propres systèmes, vérifiez auprès de votre équipe de développement ou d’ingénierie que vous utilisez la bonne URL.

Braze n’autorise que les URL qui communiquent via les ports standard 80 (HTTP) et 443 (HTTPS).

Utiliser Liquid

Vous pouvez personnaliser les URL de vos webhooks avec Liquid. Certains endpoints peuvent exiger que vous identifiiez un utilisateur ou que vous fournissiez des informations propres à l’utilisateur dans l’URL. Lorsque vous utilisez Liquid, veillez à inclure une valeur par défaut pour chaque information propre à l’utilisateur utilisée dans votre URL.

Méthode HTTP

La méthode HTTP à utiliser dépend de l’endpoint auquel vous envoyez les informations. Dans la plupart des cas, vous utiliserez POST.

Corps de la requête

Le corps de la requête correspond aux informations envoyées à l’URL que vous avez indiquée. Vous pouvez créer le corps de votre requête webhook avec des paires clé-valeur JSON ou du texte brut.

Paires clé-valeur JSON

Les paires clé-valeur JSON vous permettent de rédiger facilement une requête pour un endpoint qui attend un format JSON. Cette option ne fonctionne qu’avec un endpoint qui attend une requête JSON. Par exemple, si votre clé est message_body, la valeur correspondante pourrait être Your order just arrived!. Une fois votre paire clé-valeur saisie, le compositeur configure votre requête en syntaxe JSON et un aperçu de votre requête JSON s’affiche automatiquement.

Vous pouvez personnaliser vos paires clé-valeur avec Liquid, par exemple en incluant n’importe quel attribut utilisateur, attribut personnalisé ou propriété d’événement dans votre requête. Vous pouvez ainsi inclure le prénom et l’adresse e-mail d’un client. Veillez à inclure une valeur par défaut pour chaque attribut.

Texte brut

L’option texte brut vous offre la flexibilité de rédiger une requête pour un endpoint qui attend un corps dans n’importe quel format. Vous pouvez par exemple l’utiliser pour rédiger une requête destinée à un endpoint qui attend une requête au format XML.

La personnalisation et les étiquettes de traduction sont toutes deux prises en charge dans le texte brut.

Si vous définissez l’en-tête de requête Content-Type sur application/x-www-form-url-encoded, le corps de la requête doit être formaté sous forme de chaîne de caractères encodée en URL. Par exemple :

1

to={{custom_attribute.${example}}}&text=Your+order+just+arrived

Étape 3 : Configurer des paramètres supplémentaires

Utiliser un identifiant enregistré (facultatif)

Utilisez un identifiant enregistré pour authentifier un webhook sans saisir son mot de passe ou son jeton dans le message. Vous pouvez réutiliser les identifiants d’authentification de base et d’authentification par jeton depuis Paramètres > Gestion des identifiants dans vos campagnes webhook, vos étapes de Canvas et vos modèles de webhook.

Chaque identifiant appartient à un seul espace de travail. Créez un identifiant dans chaque espace de travail où vous en avez besoin, y compris dans des espaces de travail distincts de développement, de staging et de production.

Pour sélectionner un identifiant existant, vous avez besoin de l’autorisation « Manage App Group » ou de l’autorisation de modification correspondante : « Edit Campaigns », « Edit Canvases » ou « Edit Webhook Templates ». Pour créer, modifier ou supprimer des identifiants, vous avez besoin de l’autorisation « Manage App Group ». Si nécessaire, demandez à l’administrateur de votre espace de travail de vous l’accorder.

1. Dans l’onglet Composer, saisissez une URL de webhook HTTPS avec un nom d’hôte fixe, par exemple https://api.example.com/events. Vous pouvez utiliser Liquid dans le chemin ou les paramètres de requête, mais le nom d’hôte doit être statique pour pouvoir sélectionner un identifiant.
2. Dans Identifiant, sélectionnez un identifiant enregistré. La liste affiche les identifiants dont le domaine autorisé correspond au nom d’hôte de l’URL, y compris ceux qui autorisent un domaine parent.
3. Si vous êtes autorisé à créer des identifiants, sélectionnez Ajouter un identifiant dans le sélecteur pour en créer un. Sélectionnez Authentification de base ou Authentification par jeton, saisissez un nom d’identifiant unique et les informations d’authentification, puis sélectionnez Ajouter un identifiant. Le domaine autorisé est renseigné à partir du nom d’hôte du webhook et ne peut pas être modifié dans ce formulaire.
4. Vérifiez l’identifiant sélectionné avant d’enregistrer ou d’envoyer un webhook de test.

Si votre nom d’hôte provient de Liquid ou d’un bloc de contenu, gérez l’authentification dans les en-têtes de requête. Pour utiliser un identifiant enregistré, modifiez l’URL afin qu’elle utilise un nom d’hôte fixe et placez les valeurs dynamiques dans le chemin ou les paramètres de requête.

Les deux types d’identifiants nécessitent un domaine autorisé pour être utilisés avec des webhooks. Un identifiant d’authentification de base sans domaine reste utilisable pour le contenu connecté, mais il n’apparaît pas dans le sélecteur du webhook. Consultez la colonne Disponible dans de la page Gestion des identifiants pour vérifier si un identifiant prend en charge les webhooks. Pour des exemples de configuration et de domaines, consultez Types d’authentification.

Avertissement

Le domaine autorisé d’un identifiant inclut tous ses sous-domaines. Utilisez le nom d’hôte le plus précis que contrôle votre organisation. Un domaine parent partagé peut permettre au sous-domaine d’une autre organisation de recevoir votre identifiant. Consultez Choisir un domaine autorisé.

Braze applique l’authentification enregistrée lors de l’envoi de la requête. L’authentification de base fournit l’en-tête Authorization. L’authentification par jeton fournit les en-têtes enregistrés dans l’identifiant. Si vous saisissez manuellement un en-tête portant le même nom, la valeur de l’identifiant enregistré est prioritaire. Les noms d’en-têtes ne sont pas sensibles à la casse.

Si vous modifiez l’URL de sorte que l’identifiant sélectionné ne correspond plus, le compositeur efface la sélection. Sélectionnez à nouveau un identifiant correspondant avant d’enregistrer. Braze valide également l’identifiant et l’URL de destination générée au moment de l’envoi. Un identifiant non valide ou une destination non autorisée empêche l’envoi du webhook.

Pour mettre à jour ou supprimer un identifiant enregistré, consultez Gérer les identifiants enregistrés.

Prévisualiser les identifiants enregistrés

L’aperçu du webhook affiche l’URL générée, le corps et les en-têtes de requête saisis manuellement. Il n’affiche ni la référence à l’identifiant sélectionné ni les en-têtes d’authentification fournis par cet identifiant, plutôt que de montrer des valeurs masquées. Braze applique l’identifiant enregistré lors de l’envoi d’un webhook de test ou en production.

Dans le compositeur, les utilisateurs qui ne disposent pas de l’autorisation « Manage App Group » ou de l’autorisation de modification correspondante voient Masqué dans le sélecteur Identifiant désactivé lorsqu’un identifiant est sélectionné. Ils ne peuvent ni consulter ni modifier la sélection.

En-têtes de requête (facultatif)

Certains endpoints peuvent exiger que vous incluiez des en-têtes dans votre requête. Dans la section Composer du compositeur, vous pouvez ajouter autant d’en-têtes que nécessaire.

Les en-têtes de requête les plus courants sont les spécifications Content-Type (qui décrivent le type de données attendu dans le corps, comme XML ou JSON) et les en-têtes Authorization, qui contiennent vos identifiants auprès de votre fournisseur ou de votre système.

Remarque

Les noms d’en-têtes HTTP ne sont pas sensibles à la casse, conformément à la RFC 7230, section 3.2 (« Each header field consists of a case-insensitive field name »). Si votre endpoint de réception ou un service intermédiaire (comme un CDN) modifie la casse des en-têtes, cela n’affecte pas leur traitement : Content-Type, content-type et CONTENT-TYPE sont tous traités de la même manière.

Les spécifications de type de contenu doivent utiliser la clé Content-Type. Les valeurs courantes sont application/json ou application/x-www-form-urlencoded.

Les en-têtes d’autorisation doivent utiliser la clé Authorization. Les valeurs courantes sont Bearer {{YOUR_TOKEN}} ou Basic {{YOUR_TOKEN}} , où YOUR_TOKEN correspond aux identifiants fournis par votre fournisseur ou votre système.

Étape 4 : Tester l’envoi de votre message

Avant de mettre votre campagne en ligne, Braze vous recommande de tester le webhook pour vous assurer que la requête est correctement formatée. Si vous avez sélectionné un identifiant enregistré, l’envoi de test l’utilise pour authentifier la requête.

Pour ce faire, passez à l’onglet Test et envoyez un webhook de test. Vous pouvez tester le webhook en tant qu’utilisateur aléatoire, en tant qu’utilisateur spécifique (en saisissant son adresse e-mail ou son ID d’utilisateur externe), ou en tant qu’utilisateur personnalisé avec les attributs de votre choix.

Après l’envoi du webhook de test, une boîte de dialogue s’affiche avec le message de réponse. Si la requête webhook échoue, consultez le message d’erreur pour vous aider à résoudre les problèmes de votre webhook. L’exemple suivant présente la réponse d’un webhook dont l’URL est invalide.

1
2
3
4
5
6
7
8
9

404 Not Found

{
  "error": {
    "message": "Unrecognized request URL. Please see https://lob.com/docs or email us at [email protected].",
    "status_code": 404
  }
}

Pour plus d’informations, consultez Envoyer des messages de test.

Étape 5 : Créer le reste de votre Campaign ou Canvas

• campaign
• canvas

Ensuite, créez le reste de votre Campaign. Consultez les sections suivantes pour savoir comment tirer le meilleur parti de nos outils pour créer des webhooks.

Choisir la planification ou le déclencheur de livraison

Les webhooks peuvent être livrés à une heure planifiée, à la suite d’une action ou via un déclencheur API. Pour en savoir plus, consultez la section Planifier votre Campaign.

Pour la livraison par événement, vous pouvez également définir la durée de la Campaign et les heures calmes.

C’est également à cette étape que vous pouvez définir les contrôles de livraison, par exemple permettre aux utilisateurs de redevenir éligibles pour recevoir la Campaign, ou activer des règles de limite de fréquence.

Choisir les utilisateurs à cibler

Ensuite, vous devez cibler des utilisateurs en choisissant des Segments ou des filtres pour affiner votre audience. À cette étape, vous sélectionnez l’audience globale à partir de vos Segments, puis vous pouvez affiner davantage ce Segment avec nos filtres si vous le souhaitez. Vous obtenez automatiquement un aperçu de la population approximative de ce Segment. Gardez à l’esprit que l’appartenance exacte à un Segment est toujours calculée juste avant l’envoi du message.

Important

Votre message ne sera envoyé qu’aux utilisateurs qui correspondent déjà aux conditions que vous avez définies à l’étape Audience cible. Ensuite, ils devront toujours satisfaire le déclencheur que vous définissez à l’étape Planification de la distribution. Considérez l’audience cible comme une salle d’attente : seules les personnes qui s’y trouvent déjà peuvent avancer lorsque l’action suivante se produit.

Choisir les événements de conversion

Braze vous permet de suivre la fréquence à laquelle les utilisateurs effectuent des actions spécifiques, appelées événements de conversion, après avoir reçu une Campaign. Vous pouvez définir une fenêtre allant jusqu’à 30 jours pendant laquelle une conversion est comptabilisée si l’utilisateur effectue l’action spécifiée.

Si ce n’est pas déjà fait, complétez les sections restantes de votre étape du canvas. Pour en savoir plus sur la création du reste de votre Canvas, notamment les tests multivariés et la fonctionnalité Optimiser avec BrazeAI^TM, consultez la section Créer votre Canvas.

Étape 6 : Vérifier et déployer

Une fois la dernière étape de votre Campaign ou de votre Canvas terminée, vérifiez-en les détails, testez-le, puis envoyez-le !

Ce qu’il faut savoir

Erreurs, logique de nouvelle tentative et délais d’expiration

Les webhooks reposent sur des requêtes envoyées par les serveurs de Braze vers un endpoint externe, et des erreurs peuvent parfois survenir. Les plus courantes sont les erreurs de syntaxe, les clés API expirées, les limites de débit et les problèmes inattendus côté serveur. Avant d’envoyer une campagne webhook :

• Testez votre webhook pour détecter les erreurs de syntaxe
• Assurez-vous que les variables personnalisées ont des valeurs par défaut

Si l’envoi de votre webhook échoue, un message d’erreur est enregistré dans le journal d’activité des messages. Il indique notamment l’horodatage de l’erreur, le nom de l’application et des détails sur l’erreur.

Si le message d’erreur ne permet pas d’identifier clairement sa source, consultez la documentation de l’endpoint API que vous utilisez. Elle explique généralement les codes d’erreur utilisés par l’endpoint ainsi que leurs causes habituelles.

Codes de réponse et logique de nouvelle tentative

Lorsque la requête webhook est envoyée, le serveur destinataire renvoie un code de réponse indiquant ce qu’il est advenu de la requête. Le tableau suivant résume les différentes réponses que le serveur peut envoyer, leur impact sur l’analyse des campagnes et si, en cas d’erreur, Braze tentera de renvoyer la campagne :

Remarque

Braze relance les codes de statut éligibles mentionnés dans cette section jusqu’à cinq tentatives au total (la requête initiale plus quatre nouvelles tentatives), avec un délai croissant entre chaque tentative. Si Braze ne parvient pas à joindre votre endpoint, les nouvelles tentatives peuvent se poursuivre pendant 24 heures maximum.

Chaque requête webhook dispose de 120 secondes avant l’expiration du délai.

Les en-têtes de réponse Retry-After et de limite de débit peuvent influer sur le temps d’attente de Braze avant une tentative éligible à une nouvelle tentative (par exemple, après une réponse 408, 429 ou 5XX). Ils ne rendent pas éligibles à une nouvelle tentative les réponses qui ne le sont pas, comme 401.

Remarque

Si des envois de webhook semblent absents des analyses, ouvrez le journal d’activité des messages pour la campagne ou l’étape du canvas concernée. Braze ne relance que certaines réponses (par exemple 408, 429 et 5XX). La plupart des autres erreurs client 4XX, y compris 401 Unauthorized, ne font pas l’objet de nouvelles tentatives. Pour le tableau complet des réponses, consultez Codes de réponse et logique de nouvelle tentative.

403 Forbidden et liste d’adresses IP autorisées {#403-forbidden-and-ip-allowlisting} {#403-forbidden-and-ip-allowlisting}

Une réponse 403 Forbidden signifie que votre endpoint a bien reçu la requête, mais l’a refusée. Les causes courantes sont une authentification invalide ou manquante, des autorisations API insuffisantes et des règles réseau (comme un pare-feu ou un pare-feu d’application web) qui bloquent les adresses IP sortantes de Braze.

Si les requêtes webhook renvoient systématiquement 403 alors que vos en-têtes d’authentification sont corrects, ajoutez les adresses IP de Braze correspondant à votre cluster à la liste d’autorisation du serveur qui reçoit le webhook. Consultez Liste d’adresses IP autorisées. Les requêtes de contenu connecté utilisent les mêmes adresses IP sortantes ; consultez Liste d’adresses IP autorisées pour le contenu connecté.

Pour d’autres étapes de résolution des problèmes liés aux erreurs 4XX, consultez Résolution des problèmes liés aux requêtes webhook et de contenu connecté.

Authentification et identifiants de contenu connecté

Sélectionnez un identifiant dans le générateur de webhook pour authentifier la requête sortante. Sur cette page, consultez Utiliser un identifiant enregistré.

Les options Liquid :basic_auth et :auth_credentials authentifient uniquement l’appel {% connected_content %} dans lequel elles figurent. Elles ne sélectionnent pas d’identifiant pour la requête webhook principale. Pour récupérer un jeton ou un secret au moment de l’envoi, vous pouvez placer une étiquette {% connected_content %} dans un champ d’en-tête ou de corps afin que Liquid la résolve avant l’envoi du webhook.

Modèles de webhook enregistrés et utilisation dans les campagnes

Braze ne propose pas de rapport intégré répertoriant chaque campagne ou étape du canvas qui fait référence à un modèle de webhook enregistré donné. Pour auditer son utilisation, passez en revue les étapes webhook qui utilisent la même URL et la même méthode HTTP, ou contactez l’assistance Braze.

Résolution des problèmes et détails supplémentaires sur les erreurs

Pour des explications détaillées, des étapes de résolution des problèmes et des conseils pour corriger des erreurs de webhook spécifiques, consultez Résolution des problèmes liés aux requêtes webhook et de contenu connecté. Vous y trouverez également des explications sur le fonctionnement de notre système de détection des hôtes défaillants et sur la manière dont Braze fournit des notifications d’erreur par e-mails automatisés et via une journalisation supplémentaire dans Braze Currents.

Liste d’adresses IP autorisées

Lorsqu’un webhook est envoyé depuis Braze, les serveurs de Braze effectuent des requêtes réseau vers les serveurs de nos clients ou de tiers. La liste d’adresses IP autorisées vous permet de vérifier que les requêtes webhook proviennent bien de Braze, ce qui ajoute une couche de sécurité.

Braze enverra les webhooks depuis les adresses IP suivantes. Les adresses IP répertoriées sont automatiquement et dynamiquement ajoutées à toutes les clés API pour lesquelles la liste d’autorisation a été activée.

Important

Si vous créez un webhook de Braze à Braze et que vous utilisez une liste d’autorisation, vous devez autoriser toutes les adresses IP suivantes, y compris 127.0.0.1.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

Supprimer des utilisateurs

Pour supprimer un utilisateur individuel ou un segment d’utilisateurs, accédez à Audience > Gérer l’audience > Supprimer des utilisateurs. Le tableau de bord prend en charge la suppression groupée par segment (jusqu’à 25 millions de profils), inclut une période d’annulation de 7 jours et ne consomme pas les limites de débit partagées de la REST API. Pour connaître les étapes, les limites et les autorisations, consultez Supprimer des utilisateurs.

Pour une suppression programmatique par lots plus petits, utilisez l’endpoint /users/delete plutôt qu’une campagne webhook.