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 Campaign 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 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 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 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 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 insérer votre texte à l’endroit approprié 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, notez que l’apparence finale des messages de droite à gauche dépend en grande partie de la manière dont les fournisseurs de services les affichent. Pour connaître 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 vos URL de webhook en utilisant Liquid. Parfois, certains endpoints peuvent nécessiter que vous identifiiez un utilisateur ou fournissiez des informations spécifiques à l’utilisateur dans votre URL. Lorsque vous utilisez Liquid, veillez à inclure une valeur par défaut pour chaque 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 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 webhook avec des paires clé-valeur JSON ou du texte brut.

Paires clé-valeur JSON

Les paires clé-valeur JSON vous permettent d’écrire 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 composeur configurera votre requête en syntaxe JSON, et un aperçu de votre requête JSON s’affichera automatiquement.

Vous pouvez personnaliser vos paires clé-valeur en utilisant Liquid, par exemple en incluant 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é d’écrire une requête pour un endpoint qui attend un corps dans n’importe quel format. Par exemple, vous pouvez l’utiliser pour écrire 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 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 : Envoyez un message test

Avant de lancer votre campagne, Braze recommande de tester le webhook pour vous assurer 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î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 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 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 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 parmi vos Segments, puis affinez 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 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 ce n’est pas déjà fait, complétez les sections restantes de votre étape Canvas. Pour plus de détails sur la façon de construire le reste de votre Canvas, mettre en œuvre des tests multivariés et la sélection intelligente, et plus encore, consultez l’étape Créer votre Canvas de notre documentation Canvas.

Étape 6 : Vérifier et déployer

Après avoir terminé la création de votre dernière Campaign ou de votre dernier Canvas, vérifiez 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 les serveurs Braze qui envoient des requêtes à un endpoint externe, et des erreurs peuvent parfois survenir. 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 à s’envoyer, 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 d’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 effectue de nouvelles tentatives pour les codes de statut mentionnés plus haut dans cette section, jusqu’à cinq fois en 30 minutes en utilisant des délais exponentiels. Si nous ne parvenons pas à atteindre votre endpoint, les nouvelles tentatives peuvent s’étaler sur une période de 24 heures.

Chaque webhook dispose de 90 secondes avant d’expirer.

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 réessayable (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 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 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’IP {#403-forbidden-and-ip-allowlisting} {#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 d’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 renvoient systématiquement 403 et que vos en-têtes d’authentification sont corrects, ajoutez les IP de Braze pour votre cluster à la liste d’autorisation sur le serveur qui reçoit le webhook. Consultez Liste d’autorisation d’IP. Les requêtes de contenu connecté utilisent les mêmes IP sortantes ; consultez Liste d’autorisation d’IP pour le contenu connecté.

Pour les 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 sur le 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 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 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 supplémentaires 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 via des e-mails automatisés et une journalisation supplémentaire dans Braze Currents.

Liste d’autorisation d’IP

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

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

Important

Si vous effectuez un webhook de Braze vers Braze et que vous utilisez la liste d’autorisation, vous devez ajouter toutes les 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.