Webhooks ​

Les webhooks permettent de notifier un serveur externe lors d’évènements particuliers sur un jeu concours clickncom

Paramétrage ​

Le paramétrage des webhooks se fait depuis l'éditeur de votre jeu concours dans l'onglet Paramètres > Webhooks Cet onglet est accessible sur les offres ayant l’option dédiée activée.

Cette page présente la liste des webhooks actifs sur votre jeu concours, pour en ajouter un, cliquez sur Ajouter un weebhook.

Un webhook est défini par :

• Son type : clickncom vous propose 4 webhooks qui vont être appelés à différents moments des participations à votre jeu concours
  • Validation de formulaire : Lorsqu'un participant valide des données de formulaire, le webhook sera appelé. S'il y a plusieurs formulaires sur le jeu concours, le webhook sera appelé plusieurs fois pour une même participation. Pensez à sélectionner un critère discriminant dans les données à envoyer (telle que l'adresse email) pour faire le rapprochement.
  • Un lot est attribué à un participant : Ce webhook n'est appelé qu'en instants gagnants. Lorsqu'un lot est attribué, le webhook est appelé.
  • Un lot qui n'est pas un lot par défaut est attribué à un participant : Ce webhook n'est appelé qu'en instants gagnants. Lorsqu'un lot est attribué et que ce lot n'est pas un lot par défaut, le webhook est appelé.
  • Le participant vient de terminer le jeu : Ce webhook sera appelé au moment ou la page de jeu est finalisée par un participant. Ce webhook permet de recevoir les résultats du jeu.
• Une url : c'est un service externe, que vous pouvez être amené à développer qui sera appelé lorsque le webhook se déclenche
• Une liste d'éléments : l'interface vous propose la liste de tous les éléments disponibles au moment ou le webhook se déclenche. Vous pouvez choisir ceux que vous voulez envoyer et choisir le nom de l'attribut qui sera utilisé pour transmettre la valeur concernée. Par défaut, un attribut keyest créé avec une valeur aléatoire. Cela permet à votre service externe d'identifier le webhook de façon unique.

Une fois le paramétrage effectué, vous pouvez cliquer sur "Tester", cela envoi des données de test avec la structure choisie sur le service que vous avez paramétré.

Dans la liste, un bouton avec une icone d'oeil vous permet de voir des statistiques d'utiilisation du webhook, vous retrouvez :

• le nombre d'appels
• le nombre d'appels en erreur
• la date du dernier appel
• la dernière réponse reçue du serveur distant
• la dernière erreur rencontrée

Si vous commencez l'url de votre webhook par mailto: suivi d'une liste dd'adresses email séparée par des ,, un mail sera envoyé avec les données souhaitées

Exemples ​

Voici quelques exemples d'usage possible :

• Recrutement sans CV : utilisez Clickncom pour faire du recrutement. Proposez un sondaage avec quelques questions sur les motivations des candidats et recevez les réponses par email instantanément grace au webhook
• Jouer un son en magasin lorsqu'un lot est gagné. Utilisez un webhook pour notifier un serveur via une socket d'un gain. Lorssque ce serveur reçoit l'info il joue un son sur un appareil dédié.
• Sécuriser l'identification externe : vous avez paramétré l'accès à votre jeu concours via l'identification externe et vous souhaitez marquer les tokens comme utilisés dès qu'un participant utilise un token temporaire, créez un webhook sur la validation de formulaire qui envoi le token qui a permi la participation à votre service.
• Recevoir un email avec les données des participants qui gagnent les lots du jeu concours afin de les contacter. Ainsi, vous serez notifiés instantanément lorsqu'un lot est gagné
• Afficher sur mon site, à coté du jeu concours, une liste des lots gagnés en temps réel
• Alimenter en temps réel la carte fidélité ou le compte client des gagnants avec le lot qu'ils ont gagné.

Endpoint de test ​

Afin de vous aider à tester et à implémenter votre besoin, Clickncom vous propose un service de test vous permettant de tester de bout en bout les webhooks

Utilisation ​

L'url de ce service est https://dispatcher.clickncom.com. C'est l'url que vous devez renseigner comme url de votre webhook.

Ensuite, ouvrez cette page : https://dispatcher.clickncom.com/test.html et dans la zone dédiée, mettez la clé de votre webhook (la valeur de l'élément key). Vous verrez en temps réel les valeurs qui sont envoyées par un jeu concours publié lorsque des participants jouent.

Code ​

Ce serveur reçoit toutes les demandes et permet à des sockets de se connecter pour écouter une clé particulière.

Si vous souhaitez l'utiliser pour d'autres besoin, il vous suffit d'adapter le code ci dessous. Ce code est une page html, qui peut être insérée sous forme de widget sur n'importe quelle site web par exemple, qui affiche en temps réel les lots gagnés sur un jeu concours clickncom.

Il suffit de creér un webhook de type "lorsqu'un lot est gagné", et d'ajouter un élément lot_name qui contient le nom du lot gagné. Dans le code ci dessous, il faut changer YOUR KEY par la valeur de l'élément key du webhook.

<!DOCTYPE html>
<html>
  <head>
  <script
    src="https://cdn.socket.io/4.5.4/socket.io.min.js"
    integrity="sha384-/KNQL8Nu5gCHLqwqfQjA689Hhoqgi2S84SNUxC3roTe4EhJ9AfLkp8QiQcU8AMzI"
    crossorigin="anonymous"
  ></script>

  <script>
    let socket
    const connect = (key) => {
      socket = io("ws://dispatcher.clickncom.com", {
        reconnectionDelayMax: 30000,
        query: {
          key,
        },
      });
      socket.on("connect", () => {
        console.log("Connected to listen messages for key ", key, socket.id);
      });
      socket.on("message", (mess) => {
        let div = document.createElement("div");
        div.className = "message";
        div.innerHTML = mess.lot_name; // écrit un div contenant le nom du lot gagné
        let lots = document.getElementById("lots")
        lots.appendChild(div);
      });
    }
    const disconnect = () => {
      socket.disconnect()
    }
    connect("YOUR KEY") // change your key
    const connectWithValue = () => {
      disconnect()
      let inp = document.getElementById("key")
      connect(inp.value)
      return false
    }
  </script>
  <body>
    <div id="lots">
    </div>
  </body>
</html>

Exemple d'implémentation du endpoint ​

Le module ci dessous est un module NodeJS basé sur Express

module.exports = function (app, io) {
  app.post("/", function (req, res) {
    if (req.body) {
        // afiche le nom du lot reçu
        console.log(req.body.lot_name)
    }
    res.json({ ok: true });
  });
});

Données récupérables ​

Au travers du webhook, il est possible de récupérer des données liées à la participation :

• ip du participant (seuls les deux premiers chiffres de l'ip sont accessibles)
• données de formulaire (tous les champs de formulaire du jeu concours peuvent être envoyés unitairement)
• token (token unique interne à clickncom de participation)

Mais également des données liéées au jeu :

• score du participant si le jeu est un jeu à score
• réponses aux questions si le jeu est un quiz, un sondage ou blindtest

Des données liées à l'identification externe si celle ci est active

• token externe qui a permis l'identification
• résultat de l'identification externe (les données renvyées par le serveur externe au moment de l'identification)

Des données liées au lot gagné

• identification interne clickncom du lot
• nom du lot
• paramétrage du lot

Exemple de paramétrage de lot reçu :

{
    "id": 2, /* identifiant interne du lot */
    "name": "le lot par défaut", /* nom du lot */
    "type": "consolation", /* peut être "consolation" si c'est le lot par défaut ou "lot" sinon */
    "image": 4832, /* image du lot (identifiant interne clickncom) */
    "order": 0, /* ordre du lot */
    "quantity": 0, /* quantité paramétrée du lot, 0 correspond à un lot disponible en quantité infinie */
    "valuetype": "percent", /* type de valeur du lot, par défaut "amount" ou non définie, peut être "percent" pour une valeur en pourcentage */
    "monetaryvalue": "5.00" /* valeur monétaire du lot définie, peut être un pourcentage ou un montant */
},