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 aux campagnes de communication ciblées et ponctuelles, tandis que les Canvas sont plus adaptés aux 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 et la création de rapports pour vos campagnes. 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 Tests multivariés 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édéfinis. Ensuite, créez votre webhook dans l’onglet Compose de l’éditeur.

L’onglet Compose contient 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 insérer votre texte là où il doit figurer dans le Liquid. Pour consulter la liste complète des langues disponibles, reportez-vous à Langues prises en charge.

Si vous ajoutez du contenu dans une langue qui s’écrit de droite à gauche, sachez que l’apparence finale des messages en écriture de droite à gauche dépend en grande partie de la manière dont les fournisseurs de services les affichent. Pour les bonnes pratiques de rédaction de messages de droite à gauche qui s’affichent aussi fidèlement que possible, consultez 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’endroit où vous enverrez les informations que vous capturez dans le webhook.

Si vous souhaitez envoyer des informations à un fournisseur, celui-ci devrait fournir cette URL dans sa documentation API. Si vous envoyez des informations à 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 en utilisant Liquid. Parfois, certains endpoints peuvent exiger que vous identifiiez un utilisateur ou que vous fournissiez des informations spécifiques à l’utilisateur dans votre 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 auquel vous envoyez des informations. Dans la plupart des cas, vous utiliserez POST.

Corps de la requête

Le corps de la requête contient les informations qui seront envoyées à l’URL que vous avez spécifié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. 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 configurera votre requête en syntaxe JSON, et un aperçu de votre requête JSON sera automatiquement généré.

Vous pouvez personnaliser vos paires clé-valeur en utilisant Liquid, en incluant par exemple n’importe quel 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 utiliser cette option 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 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 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 sont insensibles à 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 tout service intermédiaire (comme les CDN) transforme 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 : Envoi test de votre message

Avant de lancer votre campagne, Braze vous 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 de test. Vous pouvez tester le webhook en tant qu’utilisateur aléatoire, utilisateur spécifique (en saisissant son adresse e-mail ou son ID utilisateur externe), ou utilisateur personnalisé avec les attributs de votre choix.

Après l’envoi du webhook de test, une boîte de dialogue apparaîtra 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 de test.

Étape 5 : Construire le reste de votre campagne ou Canvas

• campaign
• canvas

Ensuite, construisez 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 de livraison ou le déclencheur

Les webhooks peuvent être envoyés selon un horaire planifié, 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 des 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. À cette étape, vous sélectionnez l’audience plus large parmi vos segments, puis affinez davantage ce segment avec nos filtres, si vous le souhaitez. Vous recevez automatiquement un aperçu de la taille approximative de la population 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, les événements de conversion, après avoir reçu une campagne. Vous avez la possibilité d’autoriser une fenêtre allant jusqu’à 30 jours pendant laquelle une conversion sera comptabilisée si l’utilisateur effectue l’action spécifiée.

Si vous ne l’avez pas encore fait, complétez les sections restantes de votre étape Canvas. Pour plus de détails sur la construction du reste de votre Canvas, y compris les tests multivariés et l’optimisation avec BrazeAI^TM, consultez Construire votre Canvas.

Étape 6 : Vérifier et déployer

Une fois que vous avez terminé de créer la dernière de vos Campaigns ou Canvas, vérifiez les détails, testez-la, puis envoyez-la !

Ce qu’il faut savoir

Erreurs, logique de réessai et délais d’expiration

Les webhooks reposent sur les serveurs de Braze pour envoyer des requêtes à 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 Campaign 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 à s’envoyer, un message d’erreur est consigné 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 à l’origine de l’erreur, vous devriez consulter la documentation de l’endpoint 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 réessai

Lorsque la requête webhook est envoyée, le serveur récepteur 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 les analyses de la Campaign, et si, en cas d’erreur, Braze tentera de redistribuer la Campaign :

Remarque

Braze réessaie les codes de statut mentionnés précédemment dans cette section jusqu’à cinq fois en 30 minutes en utilisant des délais exponentiels. Si nous ne parvenons pas à atteindre votre endpoint, les réessais peuvent s’étaler sur une période de 24 heures.

Chaque webhook dispose d’un délai d’expiration de 90 secondes.

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

Remarque

Si des envois de webhooks semblent manquer dans les analyses, ouvrez le journal d’activité des messages pour la Campaign ou l’étape Canvas. Braze ne réessaie 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 réessais. Pour le tableau complet des réponses, consultez Codes de réponse et logique de réessai.

403 Forbidden et liste d’adresses IP autorisées {#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 correspondant à votre cluster à la liste autorisée sur le 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 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’utilisation d’identifiants de contenu connecté (:basic_auth ou :auth_credentials) pour s’authentifier auprès de votre endpoint. Configurez plutôt l’authentification en utilisant les en-têtes de requête sur le webhook. 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 Campaigns

Braze ne fournit pas de rapport intégré listant chaque Campaign ou étape Canvas faisant référence à un modèle de webhook enregistré donné. Pour auditer l’utilisation, examinez les étapes 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 supplémentaires sur les erreurs

Pour des explications détaillées, des étapes de résolution des problèmes et des conseils sur la résolution d’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 façon dont Braze fournit des notifications d’erreur par e-mails automatisés et 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. Grâce à la liste d’adresses IP autorisées, vous pouvez vérifier que les requêtes webhook proviennent bien de Braze, ajoutant ainsi une couche de sécurité supplémentaire.

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 qui ont été activées pour l’autorisation.

Important

Si vous effectuez un webhook de Braze à Braze et que vous utilisez la liste d’adresses autorisées, 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 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 Campaign de webhook.