Webhook

À propos

Un webhook sert à notifier une tierce application qu’un événement a eu lieu. Ainsi, vous pouvez demander à ce que des notifications soient envoyées sur une page de votre choix pour vous aviser de divers événements survenus dans Dialog Insight. Les webhooks vous permettent donc de recevoir les informations qui vous importent dès qu'elles surviennent, automatiquement.

Pour se servir d'un webhook, il faut fournir une adresse URL de réception à laquelle envoyer les notifications et sélectionner quand et où vous voulez recevoir des informations sur des événements touchant vos contacts. Dialog Insight envoie alors ces informations sur le serveur de votre choix dès que les événements associés surviennent. Vous devez ensuite confirmer à Dialog Insight que vous avez reçu cette notification pour qu'elle puisse arrêter de l'envoyer.

L'objectif d'un webhook est de transférer des informations aux clients, sans avoir recours aux services Web, qui peuvent être plus difficiles à mettre en place. Il est important de noter que les webhooks servent uniquement à envoyer des informations de Dialog Insight vers le serveur du client; le transfert de données dans l'autre sens n'est possible que par service Web.

Voici les événements dont vous pouvez être informés en temps réel :

• erreurs de livraison
• erreurs de production
• ajouts de nouveaux contacts, autre que par import
• mises à jour de contacts, autre que par import
• abonnements
• désabonnements
• mises en quarantaine

Exemple du processus :

1. La date de naissance d'un contact est modifiée dans Dialog Insight.
2. Dialog Insight envoie une notification sur l'URL spécifiée du client (tous les champs du projet sont fournis).
3. Le client doit confirmer la réception de cette notification le plus rapidement possible afin d'éviter des envois répétitifs de la même requête.
4. Le client traite les informations reçues conformément aux procédures automatisées qu'il aura mises en place (mise à jour du CRM, envoi d'un courriel à un responsable, etc.)

Configuration

Les webhooks permettent à votre application de recevoir les données en temps réel d'un ou de plusieurs événements se produisant sur la plateforme Dialog Insight. Par exemple, recevoir les données d'un nouveau contact pour l'ajouter à votre application.

Pré-requis

Avant de procéder à la configuration, il est important de prendre connaissance des informations suivantes : L'utilisation et la configuration sont destinées à des utilisateurs avancés qui sont familiers avec la programmation. Vous, ou toute autre personne compétente, devez configurer une adresse URL de réception dans votre application afin que les notifications d'événements puissent y être envoyées. Pour voir comment se présentent les notifications de différents types d'événements, il est suggéré de créer une URL de test dans Request Bin.

Chemin d'accès

Projet > Gestion des données > Connexions externes

 Comment faire

1. Cliquez sur Créer un webhook.
2. Entrez l'URL de réception.
3. Cochez les événements dont vous voulez recevoir les données.
4. Pour chaque événement, vous pouvez voir un exemple du code JSON envoyé, tester la réception des données directement sur votre URL et, pour les erreurs de messages, spécifier les types de communication et d'envoi concernés. Par défaut, tous les types de communication et les envois unitaires pour l'événement en question sont surveillés.
   
   Description des filtres applicables aux messages       

   Filtre	Description
   Tous les types	Tous les types de communication seront suivis.
   Des types spécifiques	Seuls les types de communications sélectionnés seront suivis.
   Envoi unitaire (confirmation, service Web, test)	Seuls les envois unitaires seront suivis.
   Envoi par lot ou campagne	Les envois en lot ainsi que les campagnes seront suivis.

5. Au besoin, validez que le webhook provient bien de Dialog Insight en utilisant la signature.
   Voir explication plus bas.
6. Si vous désirez être avisé par courriel lorsqu'un webhook est en erreur ou désactivé, sélectionnez les personnes auxquelles envoyé ce courriel dans la liste déroulante de destinataires.
7. Cliquez sur Sauvegarder.
8. Lorsque prêt à utiliser, cliquez sur Activer.

Pour plus d'informations, veuillez consulter le Guide d'utilisation des webhooks.

Recevoir un webhook

Dès qu’un webhook est configuré, Dialog Insight peut émettre une requête HTTP POST sur l’URL spécifiée à chaque fois que l’événement associé au webhook se produit.

Les paramètres de la requête POST contiennent des données (au format JSON) relatives à l’événement.

Répondre à un webhook

Votre application doit confirmer la réception de la notification avec une réponse HTTP dont le code est 200 (statut = OK) . Toute réponse en dehors de cette gamme indiquera à Dialog Insight que vous n’avez pas reçu votre webhook.

Dialog Insight fera jusqu'à 5 tentatives d'envoi sur un période d'environ 2 heures.

Valider la signature (optionnel)

Si vous le désirez, vous pouvez valider que le webhook provient bien de Dialog Insight grâce à la signature qui est incluse dans l'en-tête de chaque envoi. Cette en-tête HTTP est nommée "X-DI-Signature".

Fonctionnement : 

1. Le webhook est envoyé à votre URL.
2. Votre page récupère l'en-tête HTTP nommée "X-DI-Signature".
3. Votre page valide la valeur "X-DI-Signature" avec la clé publique XML ou PEM (obtenue à la page de configuration de votre webhook).
4. Si la comparaison est valide, vous traitez les données reçues, autrement vous rejetez l'appel.

Vous trouverez ci-après des exemples de vérification de signature C# et un autre en PHP.