Les liens de rappel HTTP (webhooks) permettent à Simple Vote d’informer votre propre système chaque fois qu’un électeur vote à l’un des scrutins de votre compte. Vous pouvez les utiliser, par exemple, pour mettre à jour une base de données de membres ou un CRM au fur et à mesure que les votes sont enregistrés, sans avoir à exporter de données du Gestionnaire de scrutins.
Les liens de rappel HTTP sont offerts dans tous les comptes. Seuls les administrateurs ont accès à la section Intégrations de la page Paramètres.
Données transmises par les liens de rappel HTTP
Chaque fois qu’un électeur vote, Simple Vote crée un événement de vote. Des événements de vote sont créés pour les votes provenant de tous les modes de vote, y compris le site de vote, le vote en mode borne, la saisie manuelle de votes et le vote téléphonique.
Chaque événement de vote comprend le numéro de scrutin, l’identifiant de l’électeur et l’heure du vote. Si les champs personnalisés 1, 2 et 3 sont activés dans votre compte, leurs valeurs pour cet électeur sont également transmises.
Les choix inscrits sur le bulletin de vote ne sont jamais transmis. Les liens de rappel HTTP indiquent à votre système qu’un électeur a voté, et non la façon dont il a voté.
Comme les liens de rappel HTTP couvrent tous les scrutins de votre compte, votre système peut recevoir des événements provenant de plusieurs scrutins à la fois, par exemple lorsque vous tenez des scrutins simultanés. Utilisez le numéro de scrutin inclus dans chaque événement pour les distinguer.
Avant de commencer
La configuration des liens de rappel HTTP nécessite un point de terminaison de votre côté, c’est-à-dire une adresse URL sur votre serveur ou votre service qui peut recevoir les événements de vote. Il est généralement mis en place par votre équipe informatique ou par le fournisseur de votre système de gestion des membres. Votre point de terminaison doit :
être accessible depuis Internet à une adresse URL commençant par
https, avec un certificat SSL valide;accepter des requêtes
POSTcontenant des données JSON;répondre rapidement avec un code de statut indiquant un succès (
2xx) lorsqu’il reçoit une requête;vérifier chaque requête à l’aide de la clé secrète de signature fournie dans le Gestionnaire de scrutins.
Les détails techniques dont vos développeurs ont besoin se trouvent dans la documentation de l’API des liens de rappel HTTP. Consultez la section À propos de la documentation de l’API ci-dessous pour un aperçu de son contenu.
Configurer les liens de rappel HTTP
Dans le Gestionnaire de scrutins, cliquez sur Paramètres dans le menu du haut, puis sur Intégrations sous Paramètres avancés dans le menu de gauche. Le panneau Liens de rappel HTTP (webhooks) affiche le statut Non configuré.
Sous Clé secrète de signature, cliquez sur le bouton de copie pour copier la clé dans le presse-papiers. Vous pouvez aussi cliquer sur l’icône en forme d’œil pour afficher ou masquer la clé.
Ajoutez la clé secrète de signature à votre point de terminaison. Votre point de terminaison s’en sert pour confirmer que chaque requête provient bien de Simple Vote. Faites-le avant le test : la requête de test est signée, et votre point de terminaison a besoin de la clé pour la vérifier.
Dans le champ Adresse URL du lien de rappel HTTP, entrez l’adresse URL de votre point de terminaison. Elle doit commencer par
https.Cliquez sur Tester et sauvegarder.
Simple Vote envoie une requête de test à votre point de terminaison. Si votre point de terminaison répond avec succès, le message “Événement de test transmis. Configuration des liens de rappel HTTP sauvegardée.” s’affiche et le statut passe à Actif. À partir de ce moment, les nouveaux événements de vote sont transmis à votre point de terminaison.
Gardez votre clé secrète de signature confidentielle. Toute personne qui la possède pourrait envoyer à votre point de terminaison des requêtes qui semblent provenir de Simple Vote. Ne la communiquez qu’aux personnes qui configurent et entretiennent votre point de terminaison.
À propos de la requête de test
La requête de test contient deux exemples d’événements de vote dont le numéro de scrutin est 0. Cette valeur identifie des événements de test, et non de vrais votes. Votre point de terminaison doit vérifier la requête comme d’habitude et répondre avec succès, sans enregistrer de votes et sans exiger qu’un scrutin portant ce numéro existe.
Une requête de test est également envoyée chaque fois que vous sauvegardez une adresse URL de lien de rappel HTTP nouvelle ou modifiée.
Si le test échoue
Si votre point de terminaison ne répond pas avec succès, un message d’erreur s’affiche et vos paramètres ne sont pas sauvegardés. Le message indique la nature du problème :
Message d’erreur | Points à vérifier |
|---|---|
Échec du test du lien de rappel HTTP : votre point de terminaison a répondu avec le code HTTP [code]. Vos paramètres n’ont pas été sauvegardés. | Votre point de terminaison a reçu la requête, mais l’a refusée. Vérifiez qu’il accepte les requêtes |
Échec du test du lien de rappel HTTP : votre point de terminaison n’a pas répondu dans un délai de [nombre] secondes. Vos paramètres n’ont pas été sauvegardés. | Votre point de terminaison a mis trop de temps à répondre. Il devrait envoyer une réponse indiquant un succès immédiatement, avant d’effectuer tout traitement qui prend du temps. |
Échec du test du lien de rappel HTTP : impossible de joindre votre point de terminaison (erreur de connexion ou de certificat SSL). Vos paramètres n’ont pas été sauvegardés. | Vérifiez que l’adresse URL est exacte, que votre point de terminaison est accessible depuis Internet et que son certificat SSL est valide. |
Une fois le problème réglé, cliquez de nouveau sur Tester et sauvegarder.
Modifier l’adresse URL du lien de rappel HTTP
Pour transmettre les événements de vote à un autre point de terminaison, ajoutez la clé secrète de signature au nouveau point de terminaison, entrez son adresse URL dans le champ Adresse URL du lien de rappel HTTP, puis cliquez sur Tester et sauvegarder. La nouvelle adresse URL n’est sauvegardée que si le test réussit.
Désactiver le lien de rappel HTTP
Sur la page Intégrations, cliquez sur Désactiver le lien de rappel HTTP.
Dans la fenêtre de confirmation, cliquez sur Désactiver.
Le message Lien de rappel HTTP désactivé. s’affiche et le statut redevient Non configuré. Les événements de vote ne sont plus transmis, et l’adresse URL du lien de rappel HTTP est supprimée. La clé secrète de signature ne change pas.
Pour réactiver le lien de rappel HTTP, suivez les étapes de la section Configurer les liens de rappel HTTP : entrez de nouveau l’adresse URL, puis cliquez sur Tester et sauvegarder.
Transmission des événements de vote
Les événements de vote ne sont pas transmis un à un au moment où les votes sont enregistrés. Simple Vote regroupe les événements survenus au cours de la dernière minute et les transmet à votre point de terminaison dans une seule requête, une fois par minute. En raison de ce regroupement par lots, les événements ne sont pas forcément reçus dans l’ordre où les votes ont été enregistrés. Utilisez l’heure du vote incluse dans chaque événement si l’ordre est important pour votre système.
Chaque lot n’est transmis qu’une seule fois. Si votre point de terminaison est indisponible, répond trop lentement ou renvoie une erreur au moment où un lot est transmis, Simple Vote ne fait pas de nouvelle tentative, et les événements de vote de ce lot ne seront pas transmis. Le lien de rappel HTTP reste actif, et les lots suivants sont transmis normalement. Si votre système doit disposer d’un registre complet des électeurs ayant voté, comparez-le aux rapports offerts dans le Gestionnaire de scrutins.
À propos de la documentation de l’API
La documentation de l’API des liens de rappel HTTP s’adresse aux développeurs qui créent et entretiennent votre point de terminaison. Vous pouvez aussi l’ouvrir à partir du lien documentation sur les liens de rappel HTTP de la page Intégrations. Elle porte sur :
le format des requêtes et des événements de vote, avec un exemple;
la fréquence de transmission et les attentes relatives à la réception;
les détails concernant les requêtes de test;
la vérification de chaque requête à l’aide de la clé secrète de signature et des en-têtes de la requête;
l’historique des modifications du format des liens de rappel HTTP.