Contexte
Au moyen d'un Webhook, assessmentQ peut fournir des informations en temps réel à des plateformes externes.
assessmentQ offre les Webhooks suivants:
Session terminée
Résultats de l'activité publiés
Lorsque vous vous abonnez à l'un de ces Webhooks, assessmentQ envoie immédiatement un message à la plateforme externe lorsque l'événement attendu se produit, par exemple lorsqu'une nouvelle session est terminée ou lorsque de nouveaux résultats sont disponibles pour une activité.
En tant qu'administrateur, vous pouvez vous abonner aux Webhooks assessmentQ via le module Intégrations.
Note: L'abonnement aux Webhooks assessmentQ est également possible via l'API assessmentQ.
S'abonner à un Webhook
Procédez comme suit pour vous abonner à un Webhook:
Ouvrez le module Intégrations dans Paramètres.
Résultat: L'aperçu des abonnements aux Webhooks est affiché.Cliquez sur le bouton Ajouter dans le coin supérieur droit.
Résultat: La fenêtre popup Ajouter un abonnement Webhook s'affiche.Saisissez un nom pour votre abonnement.
Remarque: Si vous vous abonnez au Webhook de publication des résultats d'activité, le nom de l'abonnement sera affiché dans le module Rapports d'activité lorsque vous sélectionnez l'option Envoyer les résultats.
Sélectionnez l'événement auquel vous souhaitez vous abonner.
Saisissez l'URL vers laquelle les données seront envoyées lorsque le Webhook sera déclenché.
Cliquez sur Enregistrer.
Résultat: L'aperçu de l'abonnement au Webhook est mis à jour. Si vous vous êtes abonné au Webhook "Session terminée", un message sera envoyé dès qu'un participant clique sur le bouton "Terminer" dans une session. Si vous vous êtes abonné au Webhook Résultats d'activité publiés, un message sera envoyé dès qu'un analyste clique sur Envoyer les résultats d'une activité dans le module Rapports d'activité.
S’abonner via l’API assessmentQ
De la même manière que l’abonnement via le backoffice, vous pouvez également vous abonner via notre API avec l’appel suivant :
POST /v2/subscriptions
Le corps de la requête doit contenir les données suivantes :
Un nom pour le webhook
Les événements auxquels vous souhaitez vous abonner
L’URL à appeler
La clé de sécurité qui sera utilisée
Cette dernière option, la clé de sécurité, n’est pas disponible via notre backoffice assessmentQ. Elle permet d’ajouter une protection supplémentaire contre une attaque de type "Man-In-The-Middle". Si cette clé est fournie, assessmentQ ajoutera un en-tête "X-Hook-Signature" à chaque appel du webhook avec une valeur spécifique. Cette valeur est calculée en hachant le corps de l’appel selon l’algorithme HMACSHA256, en utilisant la clé de sécurité fournie comme clé de chiffrement.
Par exemple : un webhook pour une session terminée avec le corps suivant
SessionId = 123
et la clé de sécurité "abc" entraînera un en-tête "X-Hook-Signature" avec le contenu
"17c5577856d43d0d2abbf6f6530b46f8093ce1f30be862919febdb7b49d61d7b".
Confirmation de l’abonnement
Lorsque vous vous abonnez à un webhook assessmentQ, une confirmation vous sera demandée. L’enregistrement du webhook ne sera complet qu’après cette confirmation. Pour ce faire, assessmentQ enverra un appel de test à l’URL fournie. Cet appel de test est une requête POST avec un corps vide et éventuellement un en-tête "X-Hook-Secret".
Pour valider votre webhook, la réponse doit être un code HTTP 204 NoContent, avec le même en-tête et le même contenu que l’appel. Cela signifie que si l’appel de test utilise un en-tête "X-Hook-Secret" avec la valeur "abc123", votre réponse doit également le contenir.
Si vous recevez une réponse HTTP 422 BadEntity lors de l’ajout d’un webhook, cela signifie que l’URL fournie n’a pas renvoyé la réponse attendue à l’appel de test. Dans ce cas, l’ajout échouera et le webhook ne sera pas enregistré.