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 contact qui vient d'être créé pour les ajouter à votre système (application ou serveur).
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 ou vos messages. 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.
L'objectif d'un webhook est de transférer des données de DI vers votre système. Pour transférer des données dans l'autre direction, vous devez utiliser les services Web.
Attention! Cette fonctionnalité s'adresse à des utilisateurs qui ont des connaissances avancées en programmation!
|
Pour plus de détails sur les déclencheurs supportés, consultez le Guide sur les déclencheurs de webhooks.
Chemin d'accès : Projet → Gestion des données → Connexions externes |
Prérequis
- Fournir un URL de réception valide pour votre système ou application. Vous ou toute autre personne compétente devez configurer une adresse URL de réception dans votre système afin que les notifications d'événements puissent y être envoyées.
- Comprendre les principes de programmation liés à l'utilisation des webhooks (cette fonctionnalité est destinée aux utilisateurs avancés).
Étape 1 : Ajouter l'URL de réception
Suivez le chemin d'accès et cliquez sur Créer un webhook. Entrez ensuite l'URL de réception (l'URL de votre système ou application) :
Étape 2 : Sélectionner les déclencheurs
Cochez les événements (mises à jour) qui déclencheront l'envoi de données à votre système :
Pour en savoir plus sur les données envoyées lors de chaque événement, vous pouvez utiliser le bouton Exemple ou le bouton Test à droite de l'événement :
Exemple vous présentera un exemple des valeurs envoyées en JSON (cela peut différer des données réellement envoyées selon la structure de votre projet).
Tester permet d'envoyer un test directement à l'URL de réception. Les données envoyées comporteront le champ isTest avec la valeur vrai (isTest: true).
Pour pousser vos tests plus loin, vous pourriez aussi créer un webhook qui envoie les données vers un request bin. Attention de ne pas envoyer des données sensibles au request bin.
Étape 3 : Ajouter une signature
Pour ajouter une couche de protection pour valider que le webhook provient bien de Dialog Insight, vous pouvez ajouter une signature cryptographique. Cette section apparaît lorsque vous cliquez sur Sauvegarder.
La signature sera incluse dans l'en-tête de chaque envoi. Cet en-tête HTTP est nommé "X-DI-Signature".
- Le webhook est envoyé à votre URL.
- Votre page récupère l'en-tête HTTP nommé "X-DI-Signature".
- Votre page valide la valeur "X-DI-Signature" avec la clé publique XML ou PEM (obtenue à la page de configuration de votre webhook).
- Si la comparaison est valide, vous traitez les données reçues, autrement vous rejetez l'appel.
Vous trouverez à la fin de cet article des exemples téléchargeables de vérification de signature en C# et en PHP.
Étape 4 : Ajouter un certificat SSL
Pour ajouter une couche de protection, vous pouvez ajouter un certificat SSL dans la section Authentification avec un certificat client. Cette section apparaît lorsque vous cliquez sur Sauvegarder. Le certificat (qui contient une clé privée et une clé publique) peut être ajouté manuellement ou avec un fichier .pfx :
Étape 5 : Ajouter des alertes courriel
Au besoin, ajoutez des alertes pour notifier par courriel des utilisateurs de votre compte. Des alertes sont envoyées par courriel dans les situations suivantes :
- À la 1e, 10e, 100e, 1000e, 10 000e erreur de chaque journée (basé sur l’heure des serveurs Dialog Insight).
- Lorsque votre webhook est désactivé automatiquement.
Étape 6 : Configurer la réception du 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. Vous devez configurer la réception dans le webhook handler de votre système.
Les paramètres de la requête POST contiennent des données (au format JSON) relatives à l’événement.
Pour gérer les notifications reçues, il est conseillé d’accepter toutes notifications envoyées par Dialog Insight afin de les traiter dans un second temps.
Exemple en C# permettant d'accepter les notifications dans un fichier .ashx
<%@ WebHandler Language="C#" Class="WebHookHandlerExample" %>
using System;
using System.Web;
using System.IO;
using System.Text;
public class WebHookHandlerExample : IHttpHandler
{
public void ProcessRequest (HttpContext context)
{
// Read the posted JSON body
string json;
using (StreamReader stream = new
System.IO.StreamReader(context.Request.InputStream, Encoding.UTF8))
{
}
json = stream.ReadToEnd();
// Do not process event contents here : queue the event to be
processed asychronously.
// Exemple: dumping to a file
string filename = String.Format(@"C:\Temp\webhook-event-{0}.json",
Guid.NewGuid().ToString());
File.WriteAllText(filename, json);
}
public bool IsReusable
{
get { return false; }
}
}
Exemple en PHP
// Read the posted JSON body
$json = file_get_contents('php://input');
// Do not process event contents here : queue the event to be processed
asynchronously.
// Exemple: dumping to a file
$myfile = file_put_contents('C:\\temp\\webhook-event-' . uniqid('', true) .
'.json', $json);
?>
Réponses au 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 une période d'environ 2 heures.
Tentatives d'envois
Une notification est envoyée le plus rapidement possible lorsqu’une action ciblée se produit dans la plateforme Dialog Insight via un POST (http / https). Ce POST expire après un délai de 15 secondes. Et tant que nous ne recevons pas de réponse HTTP dont le statut est «OK» (code = 200), nous réessayerons quatre autres fois pendant les deux prochaines heures, selon ce qui suit :
- 1er essai : immédiat
- 2e essai : après 1 minute
- 3e essai : après 15 minutes (donc 16 minutes après que l’action se soit produite)
- 4e essai : après 30 minutes (donc 46 minutes après que l’action se soit produite)
- 5e essai : après 60 minutes (donc 101 minutes après que l’action se soit produite)
Si la notification n’a pas pu être livrée après ces tentatives, elle est mise en erreur et abandonnée.
Désactivation automatique
Les notifications se désactivent automatiquement si votre système tombe en panne, pour éviter un grand volume de messages bloqués en essais multiples. Votre système sera déclaré en panne lorsqu’au moins 100 erreurs consécutives se seront produites, et ce sur une période minimale de 8 heures. Ce webhook sera alors désactivé et une alerte transmise aux utilisateurs configurés pour recevoir les alertes associées à ce webhook.
Pour réactiver le flot des notifications, vous devrez les activer à nouveau via la plateforme. Notez que les notifications qui auraient eu lieu pendant la période de désactivation seront perdues (de même que les notifications qui étaient en attente lors de la désactivation).
Étape 7 : Activer le webhook
Lorsque vous êtes prêt à utiliser le webhook, cliquez sur Activer.
Une fois un webhook activé, Dialog Insight va envoyer toutes les modifications demandées. Selon le nombre d’interactions effectuées par les contacts ou selon le nombre d’envois en erreur, la quantité de notifications envoyées peut être très élevée. Il n’est donc pas recommandé de traiter ces notifications au fur et à mesure où elles arrivent car toute erreur ou délai de traitement peut vous faire perdre des notifications.
L’objectif de votre système qui reçoit les appels de webhooks devrait plutôt se limiter à accepter la responsabilité d’une notification le plus rapidement possible et de confirmer que la notification a été reçue.
Nous recommandons donc un système asynchrone qui enregistre directement toutes les notifications que Dialog Insight envoie, dans une base de données ou dans un fichier. Ensuite, un autre processus automatisé pourra traiter une à une les notifications enregistrées afin de produire le résultat voulu, soit l’ajout de contacts dans votre CRM, la mise à jour d’un contact selon vos règles, etc.