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 : Choisir où créer votre message

Vous ne savez pas si votre message doit être envoyé via une campagne ou un Canvas ? Les Campaigns sont plus adaptées pour des campagnes de communication uniques et ciblées, tandis que les Canvas sont plus adaptés pour des parcours utilisateur en plusieurs étapes.

• campaign
• canvas

Étapes :

1. Allez dans Messaging > Campaigns et sélectionnez Create Campaign.
2. Sélectionnez Webhook ou, pour les campagnes ciblant plusieurs canaux, sélectionnez Multichannel.
3. Donnez à votre campagne un nom clair et significatif.
4. (Facultatif) Ajoutez une description pour expliquer comment cette campagne sera utilisée.
5. Ajoutez des équipes et des tags selon vos besoins.
   • Les tags facilitent la recherche de vos campagnes 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 campagne. Vous pouvez choisir différents modèles de webhook pour chacune de vos variantes ajoutées. Pour en savoir plus sur ce sujet, consultez Test multivarié et A/B.

Conseil

Si tous les messages de votre campagne sont similaires ou ont le même contenu, composez votre message avant d’ajouter des variantes supplémentaires. Vous pouvez ensuite choisir Copy from Variant dans le menu déroulant Add Variant.

É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 choisir de créer un webhook à partir de zéro, d’utiliser un modèle existant ou d’utiliser l’un de nos modèles préexistants. Ensuite, créez votre webhook dans l’onglet Compose de l’éditeur.

L’onglet Compose comprend les champs suivants :

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

Langue

L’internationalisation est prise en charge dans l’URL et le corps de la requête. Pour internationaliser votre message, sélectionnez Add languages et remplissez les champs requis.

Nous vous recommandons de sélectionner vos langues avant de rédiger votre contenu afin de pouvoir saisir votre texte à l’endroit approprié dans le Liquid. Pour consulter la liste complète des langues disponibles, reportez-vous à la section Langues prises en charge.

Si vous ajoutez du texte dans une langue écrite de droite à gauche, sachez que l’apparence finale des messages de droite à gauche dépend en grande partie de la façon dont les fournisseurs de services les affichent. Pour connaître les bonnes pratiques de rédaction de messages de droite à gauche s’affichant aussi fidèlement que possible, consultez la section Créer des messages de droite à gauche.

URL du webhook

L’URL du webhook, ou URL HTTP, spécifie 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 doit fournir cette URL dans sa documentation d’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 communiquant via les ports standard 80 (HTTP) et 443 (HTTPS).

Utiliser Liquid

Vous pouvez personnaliser vos URL de webhook à l’aide de Liquid. Parfois, certains endpoints peuvent exiger que vous identifiiez un utilisateur ou que vous fournissiez des informations spécifiques à l’utilisateur dans l’URL. Lorsque vous utilisez Liquid, veillez à inclure une valeur par défaut pour chaque élément d’information spécifique à l’utilisateur que vous utilisez dans votre URL.

Méthode HTTP

La méthode HTTP à utiliser varie en fonction de l’endpoint vers lequel vous envoyez des informations. Dans la plupart des cas, vous utiliserez POST.

Corps de la requête

Le corps de la requête correspond aux informations qui seront envoyées à l’URL que vous avez spécifiée. Vous pouvez créer le corps de votre requête de 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. Vous ne pouvez utiliser cette option 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 que vous avez saisi votre paire clé-valeur, 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 à l’aide de Liquid, notamment en incluant tout attribut utilisateur, attribut personnalisé ou propriété d’événement dans votre requête. Par exemple, vous pouvez inclure le prénom et l’adresse e-mail d’un client dans votre requête. Veillez à inclure une valeur par défaut pour chaque attribut.

Texte brut

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

La personnalisation et l’internationalisation via Liquid sont 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é en tant que chaîne encodée en URL. Par exemple :

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

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

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

Certains endpoints peuvent nécessiter l’inclusion d’en-têtes dans votre requête. Dans la section Compose du composeur, vous pouvez ajouter autant d’en-têtes que nécessaire.

Les en-têtes de requête courants sont les spécifications Content-Type (qui décrivent le type de données attendu dans le corps de la requête, comme XML ou JSON) et les en-têtes Authorization qui contiennent vos identifiants auprès de votre fournisseur ou 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 des services intermédiaires (tels que les CDN) transforment la casse des en-têtes, cela n’affectera pas le traitement des en-têtes : Content-Type, content-type et CONTENT-TYPE sont tous traités de manière identique.

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 système.

Étape 4 : Envoyer un message test

Avant de lancer votre campagne, Braze recommande de tester le webhook pour vérifier que la requête est correctement formatée.

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

Après l’envoi du webhook test, une boîte de dialogue apparaît avec le message de réponse. Si la requête du webhook échoue, consultez le message d’erreur pour vous aider à résoudre le problème. L’exemple suivant détaille la réponse d’un webhook avec une URL de webhook 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 en savoir plus, consultez Envoyer des messages test.

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

• campaign
• canvas

Ensuite, créez le reste de votre campagne. Consultez les sections suivantes pour plus de détails sur la meilleure façon d’utiliser nos outils pour créer des webhooks.

Choisir la planification ou le déclencheur de livraison

Les webhooks peuvent être envoyés selon une planification horaire, une action ou un déclencheur API. Pour en savoir plus, consultez Planifier votre campagne.

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

Cette étape vous permet aussi de spécifier les contrôles de livraison, comme autoriser les utilisateurs à redevenir rééligibles pour recevoir la campagne, ou activer les règles de limite de fréquence.

Choisir les utilisateurs à cibler

Ensuite, vous devez cibler les utilisateurs en choisissant des Segments ou des filtres pour affiner votre audience. Au cours de cette étape, vous sélectionnez l’audience la plus large à partir de vos Segments, puis vous affinez davantage ce Segment avec nos filtres, si vous le souhaitez. Vous recevez automatiquement un aperçu de la population approximative de ce Segment. Gardez à l’esprit que l’appartenance exacte au Segment est toujours calculée 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 campagne. Vous avez la possibilité de définir une fenêtre allant jusqu’à 30 jours pendant laquelle une conversion sera 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 Canvas. Pour plus de détails sur la création du reste de votre Canvas, y compris les tests multivariés et l’option Optimiser avec BrazeAI^TM, consultez Créer votre Canvas.

Étape 6 : Vérifier et déployer

Après avoir terminé la création de votre dernière Campaign ou Canvas, vérifiez les détails, testez-la, puis envoyez-la !

Ce qu’il faut savoir

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

Les webhooks reposent sur les serveurs Braze qui effectuent des requêtes vers un endpoint externe, et des erreurs peuvent survenir occasionnellement. Les erreurs les plus courantes incluent 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 de 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 votre webhook ne parvient pas à être envoyé, un message d’erreur est enregistré dans le journal d’activité des messages et inclut des détails tels que l’horodatage de l’erreur, le nom de l’application et des informations sur l’erreur.

Si le message d’erreur n’est pas suffisamment clair quant à la source de l’erreur, vous devriez consulter la documentation de l’endpoint de l’API que vous utilisez. Celle-ci fournit généralement une explication des 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 qui s’est passé avec la requête. Le tableau suivant résume les différentes réponses que le serveur peut envoyer, leur impact sur l’analytique de la campagne et si, en cas d’erreur, Braze tentera de renvoyer la campagne :

Remarque

Braze relance les codes de statut pouvant faire l’objet d’une nouvelle tentative décrits dans cette section jusqu’à cinq tentatives au total (la requête initiale plus quatre nouvelles tentatives), avec un délai croissant entre les tentatives. Si Braze ne parvient pas à atteindre votre endpoint, les nouvelles tentatives peuvent se poursuivre jusqu’à 24 heures.

Chaque requête webhook dispose de 120 secondes avant d’expirer.

Les en-têtes de réponse Retry-After et de limitation du débit peuvent affecter le temps d’attente de Braze avant une tentative pouvant faire l’objet d’une nouvelle tentative (par exemple, après 408, 429 ou 5XX). Ils ne rendent pas les réponses non réessayables, telles que 401, éligibles à une nouvelle tentative.

Remarque

Si des envois de webhooks semblent manquer dans l’analytique, ouvrez le journal d’activité des messages pour la campagne ou l’étape Canvas. 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’autorisation d’adresses IP {#403-forbidden-and-ip-allowlisting}

Les réponses 403 Forbidden signifient que votre endpoint a reçu la requête mais l’a refusée. Les causes courantes incluent une authentification invalide ou manquante, des permissions API insuffisantes et des règles réseau (telles qu’un pare-feu ou un pare-feu applicatif web) qui bloquent les adresses IP sortantes de Braze.

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

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

Authentification et identifiants de contenu connecté

La requête HTTP sortante du webhook ne prend pas en charge l’ajout d’identifiants de contenu connecté (:basic_auth ou :auth_credentials) pour s’authentifier auprès de votre endpoint. Configurez l’authentification en utilisant les en-têtes de requête du webhook à la place. Pour récupérer un jeton ou un secret au moment de l’envoi, vous pouvez placer une balise {% 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 fournit pas de rapport intégré listant chaque campagne ou étape Canvas qui fait référence à un modèle de webhook enregistré donné. Pour auditer l’utilisation, examinez les étapes de webhook qui utilisent la même URL et la même méthode HTTP, ou contactez le support Braze.

Résolution des problèmes et détails d’erreur supplémentaires

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

Liste d’autorisation d’adresses IP

Lorsqu’un webhook est envoyé depuis Braze, les serveurs Braze effectuent des requêtes réseau vers les serveurs de nos clients ou des serveurs tiers. Avec la liste d’autorisation d’adresses IP, vous pouvez vérifier que les requêtes webhook proviennent de Braze, ajoutant ainsi une couche de sécurité.

Braze enverra les webhooks depuis les adresses IP suivantes. Les adresses IP listées sont automatiquement et dynamiquement ajoutées à toutes les clés API qui ont opté pour la liste d’autorisation.

Important

Si vous effectuez un webhook Braze-vers-Braze et utilisez la liste d’autorisation, vous devez ajouter toutes les adresses IP suivantes à la liste d’autorisation, 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 en masse de Segments (jusqu’à 10 millions de profils), inclut une fenêtre d’annulation de 7 jours et ne consomme pas les limites de débit partagées de la REST API. Pour les étapes, les limites et les permissions, consultez Supprimer des utilisateurs.

Pour une suppression programmatique par lots plus petits, utilisez l’endpoint /users/delete au lieu d’une campagne de webhook.