Webhook 2.0 : Qu'est-ce que c'est ? Comment l'utiliser ?

Les webhooks sont un outil permettant d'avertir vos systèmes externes lorsqu'une nouvelle participation se produit dans le cadre de vos campagnes Qualifio. Les détails des participations sont envoyés en temps réel à une URL que vous configurez.

Regardons de plus près à quoi ressemblent les événements que vous recevrez sur le webhook 2.0.

Qu'est-ce qu'un webhook ?

La mécanique de base des webhooks peut être considérée comme une notification "push". Au contraire d'une API, il n'est pas nécessaire d'interroger vos données toutes les quelques minutes pour savoir s'il y a de nouvelles informations. Les webhooks poussent immédiatement l'information vers l'application de votre choix, via une URL appelée point de terminaison (endpoint).

Dans Qualifio, les webhooks sont déclenchés pour chaque nouvelle participation. Lorsque cela se produit, Qualifio envoie vers votre point de terminaison une notification (en termes techniques, une requête POST au format JSON) contenant des données sur la participation. Ensuite, vous pouvez faire ce que vous voulez avec les données de participation que vous récupérez.

Versions

Lors de la configuration d'un webhook, vous pouvez sélectionner la version à utiliser. Versions actuellement supportées :

• Webhook 1.0 – Pour plus d'informations, voir Les webhooks 1.0 de Qualifio.
  
  Cette version est considérée comme obsolète à partir du 9 février 2021.
• Webhook 2.0 comprend les éléments suivants :
  
  • La version 2.0 a des événements plus riches et plus complets que la version 1.0. Elle inclut les données du questionnaire et de l'écran de sortie (score, profil, lots, etc.)
  • Vous pouvez ajouter un en-tête d'authentification. Les requêtes que vous recevrez pour le webhook contiendront la clé et la valeur requises.
  • Lorsque vous utilisez le webhook 2.0, nous vous recommandons de mettre en œuvre la vérification des charges utiles de votre côté afin de valider l'authenticité des demandes entrantes. Vérification des signatures webhook
  • Pour vous aider à effectuer une migration en douceur vers ce nouveau webhook, nous avons un guide de migration : Migration vers le webhook 2.0.

Comment mettre en place un webhook ?

Pour cette forme d'intégration, l'aide d'un développeur est souvent nécessaire. Il est également possible d'utiliser les webhooks avec Zapier.com ou Blendr.io, afin d'envoyer les informations vers n'importe quel service supporté par ces plateformes, sans vous y connaître en programmation.

1. Tout d'abord, allez à la page Webhook 2.0 dans Qualifio. Pour ce faire, rendez-vous sur la page Paramètres, dans la section Intégrations & partenaires.
2. Dans la page Webhook 2.0 :

a. Nom de cette intégration : entrez un nom d'affichage pour le webhook.
b. Définissez comment vous voulez traiter les participations incomplètes.
c. Webhook host : saisissez l'URL du système vers lequel les événements seront envoyés.

d. Authorisation header : il est possible d'authentifier les requêtes webhook en envoyant les informations de ces champs dans les en-têtes. Pour plus d'informations, consultez Sécuriser et authentifier les événements webhook pour protéger vos données
e. Webhook secret : Qualifio peut éventuellement signer les événements webhook qu'il envoie à votre point de terminaison en incluant une signature dans l'en-tête de chaque événement. Spécifiez un secret pour vérifier les événements que Qualifio envoie à vos points de terminaison webhook.
f. Une fois que vous avez ajouté votre nouveau webhook, cliquez sur Sauvegarder au bas de la page.

Vous voyez, c'est simple !

Vous pouvez ajouter un webhook pour l'ensemble de votre compte ou en créer un spécifique pour chaque site. Si vous devez créer un webhook spécifique pour une campagne, il est possible de configurer la plateforme pour ce faire. Veuillez contacter votre intermédiaire Qualifio ou notre service clientèle.

Gérer les webhooks

Si vous souhaitez personnaliser où votre webhook est activé, veuillez consulter la section Paramétrer le push de données dans Qualifio. Par exemple, être informé(e) uniquement lorsqu'une participation a lieu sur un site spécifique ou dans le cadre de campagnes spécifiques.

Exemple d'événement (payload)

Une fois qu'un webhook est déclenché, une charge utile (payload) est livrée à l'URL spécifiée. Voici un exemple de payload.

Chaque événement suit une structure JSON similaire avec des informations associées à la participation : https://integrations.qualifio.com/schemas/webhook/v2/index.html 

Test de votre webhook

Bien que nous n'offrions pas de fonctionnalité native pour tester votre webhook, il existe toute une série de services gratuits pour cela. Nous utilisons notamment webhook.site. Vous pouvez y obtenir une URL d'essai, configurer Qualifio pour envoyer des webhooks à cette URL, puis examiner les données reçues. De cette façon, vous pouvez tester votre webhook.

Foire aux questions sur les webhooks

Combien de temps faut-il pour que Qualifio mette à jour le webhook ?

Les paramètres du webhook peuvent être mis en cache pendant cinq minutes au maximum. Lorsque vous modifiez l'URL du webhook, les données d'authentification ou d'autres paramètres, il peut donc s'écouler jusqu'à cinq minutes avant que vos modifications soient prises en compte.

Qualifio fournit-il des webhooks en temps réel ?

Oui, à ceci près que nous vous envoyons un seul événement par requête. Ainsi, lorsque de nombreuses participations ont eu lieu dans un court laps de temps, n'oubliez pas que cela pourrait retarder la transmission des informations. Nous ne garantissons pas que les notifications soient reçues en temps réel (plutôt en temps quasi-réel).

Comment interpréter une différence entre les statistiques Qualifio et les données poussées ?

Il se peut que vous remarquiez des différences entre les statistiques Qualifio (statistiques de campagne ou Global Stats) et les données obtenues par le biais de webhooks. En effet, dans les statistiques Qualifio, nous considérons une participation comme terminée à condition que le formulaire ait été soumis (campagnes identifiées). Dans le cadre des webhooks, une participation sera considérée comme terminée si l'écran de sortie a été affiché.

Et voilà !

🤔 Vous avez un commentaire ou une question concernant cette rubrique ? N'hésitez pas à contacter nos agents en soumettant un ticket de support. Si vous n'avez pas encore de compte Qualifio, vous pouvez nous contacter ici.