Ce guide complète les articles existants (Le webhook et Qu'est-ce qu'un connecteur) en détaillant les types d'événements réellement transmis par les TaqtOne et leur structure JSON.

Objectif : comprendre précisément les événements émis par les bornes TaqtOne afin de construire un contrat d'interface fiable, quel que soit le type de borne.

1. Rappel : ce que le webhook envoie

Lorsqu'une borne TaqtOne émet une donnée valide, Ubiqod appelle votre URL de destination en HTTP POST. Le corps de la requête (le payload) est un objet JSON décrivant l'événement.

Il existe trois familles de payload (cf. configuration du connecteur) :

1. DATA — un appui sur un bouton et/ou un badge passé. C'est l'événement métier principal.
2. KEEP_ALIVE + WAKE_UP - Le KeepAlive est le signal de vie envoyé journalièrement, même sans utilisation de la borne. Le WakeUp est la première donnée envoyée à la première mise sous tension de la borne ou lors d’un redémarrage (reboot).
3. ALERT — déclenché quand un seuil programmé dans la borne est atteint.

Par défaut, seuls les payloads DATA sont envoyées. Les autres s'activent dans les options avancées du connecteur.

Choisir les types d'événements transmis

Dans l'onglet Options avancées du connecteur, le menu « Sélectionner les types d'événements à envoyer » détermine ce qui transite par ce webhook. Les combinaisons proposées sont :

• DATA — événements de données uniquement
• ALERT — événements d'alertes uniquement
• KEEP_ALIVE + WAKE_UP — événements de vie et de réveil uniquement
• DATA + ALERT — événements de données et d'alertes
• DATA + ALERT + KEEP_ALIVE + WAKE_UP — tous les types d'événements

Deux approches d'architecture sont possibles selon votre préférence :

• Un seul webhook pour tout : un unique endpoint reçoit tous les types. Plus simple à mettre en place ; votre code doit alors router selon eventType pour aiguiller chaque message.
• Un endpoint par type : vous créez un webhook (donc un endpoint) distinct par famille — par exemple un pour DATA, un pour ALERT, un pour KEEP_ALIVE + WAKE_UP. La scission est plus propre pour le debug et la séparation des responsabilités, au prix de plusieurs endpoints à maintenir.

Il n'y a pas de bonne réponse universelle : le choix dépend de l'architecture de votre système.

2. Structure commune à tous les événements

Tous les payloads partagent la même enveloppe. Seul le bloc data change selon le type de borne et l'action.

{
  "eventType": "DATA",                  // "DATA" | "KEEP_ALIVE" | "WAKE_UP" | "ALERT"
  "timestamp": "2026-06-12T11:00:05.000Z", // ISO 8601, UTC
  "account": { "name": "EP_1" },     // votre organisation Ubiqod

  "tracker": {                          // la borne physique qui a émis l'événement
    "id": "65413734-a5c6-4165-b445-af6475602586", // UUID stable Ubiqod
    "slug": "865456056209578",          // identifiant matériel (IMEI/numéro de série)
    "type": "IOT",
    "model": "TAQTONE",
    "label": "Aéroport | P2 Sous sol H", // nom donné à la borne
    "batteryLevel": 49,                 // % batterie (0–100)
    "externalReferences": {}            // vos clés métier (mapping ERP/CRM)
  },

  "site": { /* … ou null */ },          // site rattaché (voir §6)
  "location": "43.6668227,7.2098445",   // "lat,lng" ou "" si non géolocalisé
  "alert": null,                        // bloc d'alerte (non null seulement si ALERT)
  "data": { /* … ou null */ },          // détail de l'action (non null pour les eventType DATA uniquement)
  "ubiqodValidity": { /* … */ }         // drapeaux de validité (voir §5)
}

Champs d'identification à retenir pour votre contrat

3. Les deux grandes natures d'événement DATA

Un événement DATA issu d'une TaqtOne se résume à deux signaux, qui peuvent être combinés :

• Un appui sur un bouton → décrit par data.reference (numéro du bouton) + data.label (libellé configuré).
• Un badge passé → décrit par le bloc data.code (badge) + ubiqodValidity.badgeSwiped = true.

C'est la combinaison de ces deux signaux, et surtout le numéro de bouton (data.reference), qui donne le sens métier.
Le payload ne contient pas de champ « type de borne » : le type (Satisfaction, Pointage, Traçabilité, Service Request, Custom) résulte de la configuration de la borne, que vous traduisez via le mapping des boutons.

Bloc data — référence des champs

Bloc data.code (le badge), présent uniquement si un badge a été passé :

💡 Règle clé sur le badge. Le drapeau ubiqodValidity.codeValid indique si le badge est reconnu :

• codeValid = true → code.label = nom de la personne (badge enregistré dans une liste de badges).

• codeValid = false → code.label = UID (badge non enregistré). Le badge fonctionne quand même, mais reste anonyme.

4. Identifier le type de borne à partir du payload

Le seul type structurellement distinguable est la Satisfaction. Tous les autres types (Pointage, Traçabilité, Service Request, Custom) partagent la même structure « bouton + badge » et se différencient uniquement par le mapping des boutons que vous configurez.

┌─────────────────────────────────────────────┐
│  data.rate est un nombre ?                   │
└───────────────┬───────────────┬─────────────┘
           OUI  │               │  NON
                ▼               ▼
       ┌────────────────┐  ┌──────────────────────────────┐
       │  SATISFACTION  │  │  Événement « bouton + badge » │
       │ (code = null,  │  │  → sens donné par             │
       │  badgeSwiped   │  │     data.reference (bouton)   │
       │  = false)      │  │     + badgeSwiped / code      │
       └────────────────┘  └──────────────────────────────┘

data.reference est la clé stable : un bouton physique conserve son numéro. Le data.label reflète votre configuration et peut être renommé — utilisez-le pour l'affichage, mais basez votre logique sur reference.

4.1 Satisfaction (boutons smiley)

Une borne de satisfaction émet une note, sans badge.

Signature : data.rate présent · data.code = null · ubiqodValidity.badgeSwiped = false.

Le champ rate est normalisé (échelle de 1 à 5, 5 étant la meilleur note de satisfaction possible), indépendamment du nombre de smileys physiques. Le label donne le texte associé.

Attention les bornes Satisfaction sont aussi généralement utilisé en complément pour la traçabilité (badging). Voir paragraphe 4.3.

Exemples observés (configuration à 3 smileys) :

// Satisfaction — note « Excellent »
{
  "eventType": "DATA",
  "timestamp": "2026-06-12T10:40:01.000Z",
  "account": { "name": "EP_1" },
  "tracker": { "model": "TAQTONE", "label": "Aeroport Hall 2", "batteryLevel": 46 },
  "site": { "label": "AEROPORT | DR | NICE" },
  "data": {
    "interfaceType": "TAQTONE",
    "reference": "5",        // bouton « smiley vert »
    "label": "Excellent",    // Champ personnalisable dans "interface"
    "rate": 5,               // ← note normalisée 1–5 (présent = satisfaction)
    "email": "",
    "code": null,            // ← aucun badge
    "pressCount": 4,         // 4 appuis reçus sur ce bouton
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": false, "codeValid": false, "onSite": true }
}

4.2 Pointage (boutons Entrée / Sortie)

Un agent badge puis appuie sur un bouton « Entrée » ou « Sortie ». L'événement combine bouton + badge.

Signature : data.code présent · badgeSwiped = true · pas de rate · le label/reference du bouton porte la sémantique entrée/sortie.

// Pointage — départ de site (clock-out)
{
  "eventType": "DATA",
  "timestamp": "2026-06-12T12:12:44.000Z",
  "account": { "name": "Test_DOC" },
  "tracker": { "model": "TAQTONE", "label": " National Opéra", "batteryLevel": 74 },
  "data": {
    "interfaceType": "TAQTONE",
    "reference": "5",                 // ← bouton « Sortie »
    "label": "Departure from site",
    "code": {
      "reference": "045C723A521E90",  // UID du badge
      "label": "Damaris Rubeta"      // nom (badge connu → codeValid:true)
    },
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": true, "codeValid": true, "onSite": true }
}

Le sens « entrée » ou « sortie » dépend du bouton (reference/label) : il n'existe pas de champ dédié au pointage. Basez votre logique sur le mapping des boutons de la borne.
En règle générale le bouton “3” est dédié au pointage entrée (check-in), et le “5” au pointage sortie (check-out).

4.3 Traçabilité (badging seul)

La borne de traçabilité n'a pas de bouton : on badge simplement pour prouver un passage. Le signal déterminant est donc le badge.

Signature : data.code présent · badgeSwiped = true. Le bouton (reference/label) correspond au passage configuré par défaut.

// Traçabilité / passage badgé (badge non enregistré → label = UID)
{
  "eventType": "DATA",
  "timestamp": "2026-06-12T04:51:26.000Z",
  "account": { "name": "EP_1" },
  "tracker": { "model": "TAQTONE", "label": "865456059667008 - EP_2", "batteryLevel": 99 },
  "data": {
    "interfaceType": "TAQTONE",
    "reference": "6",
    "label": "Inter. de nettoyage (sortie)",
    "code": {
      "reference": "04549102C31B90", // UID du badge
      "label": "04549102C31B90"      // = UID car badge inconnu (codeValid:false)
    },
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": true, "codeValid": false, "onSite": true }
}

4.4 Service Request (boutons de demande d'intervention)

Un ou plusieurs boutons déclenchent une demande d'intervention (ex. « remplacement consommable », « nettoyage »). Le sens vient du bouton (reference/label).

Le badge est optionnel : une demande peut être faite par simple appui (sans badge), et un agent peut ensuite clôturer l'intervention en appuyant sur le même bouton avec son badge (voir le cas en deux temps plus bas).

Signature : pas de rate ; le label/reference identifie le type de demande ; code / badgeSwiped présents lorsqu'un badge accompagne l'appui (typiquement la clôture par un intervenant).

// Demande d'intervention — entrée de prestation
{
  "eventType": "DATA",
  "timestamp": "2026-06-10T10:28:36.000Z",
  "account": { "name": "EP_1" },
  "tracker": { "model": "TAQTONE", "label": "Altas", "batteryLevel": 100 },
  "site": { "label": "Altas - Toulouse", "location": "43.6108617,1.4347106" },
  "data": {
    "interfaceType": "TAQTONE",
    "reference": "3",                       // ← bouton « demande d'intervention »
    "label": "Demande intervention",
    "code": { "reference": "26167181000000", "label": "26167181000000" },
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": true, "codeValid": false, "onSite": true }
}

Cas en deux temps : demande puis clôture sur le même bouton

Un même bouton Service Request peut servir à la fois à ouvrir une demande puis à la clôturer. Le seul élément qui distingue les deux événements est la présence du badge (code / badgeSwiped).

1. Ouverture de la demande — un usager signale un besoin (ici un remplacement de consommable, bouton 4), sans badger :

// Service Request — ouverture d'une demande (appui seul, sans badge)
{
  "eventType": "DATA",
  "timestamp": "2026-06-26T13:38:21.000Z",
  "account": { "name": "Test_Grupo" },
  "tracker": { "model": "TAQTONE", "label": "UCA SALA 2651J C", "batteryLevel": 50 },
  "data": {
    "interfaceType": "TAQTONE",
    "reference": "4",        // ← bouton « remplacement consommable »
    "label": "Savon",        // libellé configuré (« savon »)
    "code": null,            // ← aucun badge : c'est une DEMANDE
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": false, "codeValid": false, "onSite": true }
}

2. Clôture / réalisation — plus tard, un agent réalise l'intervention et appuie sur le même bouton 4 + badge ; le badge identifie l'intervenant :

// Service Request — clôture (même bouton + badge de l'intervenant)
{
  "eventType": "DATA",
  "timestamp": "2026-06-26T14:02:02.000Z",
  "account": { "name": "Test_Grupo" },
  "tracker": { "model": "TAQTONE", "label": "UCA SALA 2651J C", "batteryLevel": 50 },
  "data": {
    "interfaceType": "TAQTONE",
    "reference": "4",        // ← même bouton
    "label": "Savon",
    "code": {
      "reference": "04405902C31B90",
      "label": "Marin Fecha",      // intervenant (badge connu → codeValid:true)
      "externalReferences": { "Category": "Cleaning" }
    },
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": true, "codeValid": true, "onSite": true }
}

💡 Côté intégration : pour ce scénario, suivez l'état d'une demande par bouton (reference). Un événement sans badge = ouverture/demande ; un événement avec badge sur le même bouton = clôture, avec l'intervenant dans code.

4.5 Custom (mélange des cas précédents)

Une borne Custom combine plusieurs fonctions sur des boutons distincts (ex. 2 boutons smiley + 3 boutons service request + badging). Il n'y a rien de spécial à détecter dans le payload : chaque appui produit un événement standard, et c'est votre table de mapping reference → signification qui distingue les fonctions.

Règle pratique de routage dans le code :

si data.rate est présent           → traiter comme SATISFACTION (note = data.rate)
sinon, selon data.reference (bouton):
    └─ appliquer le mapping configuré pour cette borne
       (Entrée / Sortie / Intervention X / Passage …)
et dans tous les cas, si data.code != null et badgeSwiped == true:
    └─ rattacher l'événement à un badge / une personne
       (nom si codeValid, sinon UID anonyme)

5. Le bloc ubiqodValidity (drapeaux de validité)

Ces booléens qualifient l'événement. Les deux plus utiles pour votre logique sont badgeSwiped et codeValid.

6. Les blocs site et account

• account.name : nom de votre organisation Ubiqod. Constant pour un même compte.
• site : le site rattaché à la borne. Peut être null si la borne n'est pas rattachée à un site. Quand il est présent :

"site": {
  "id": "2f5442a7-a532-4bf8-bb11-38b5b9e9de60",  // UUID stable du site
  "label": "NICE AEROPORT | DR NICE | NICE",
  "location": "43.6668227,7.2098445",            // "lat,lng"
  "contacts": [                                   // contacts du site
    { "type": "CUSTOMER", "fullName": "", "email": "", "phone": "" },
    { "type": "MANAGER",  "fullName": "", "email": "", "phone": "" }
  ],
  "externalReferences": {}
}

Ne supposez jamais que site est présent : gérez le cas null. Pour rattacher un site de façon fiable côté intégration, préférez site.id (ou site.externalReferences) plutôt que site.label.

7. Événements KEEP_ALIVE

Signal de vie périodique. data vaut null et eventType = "KEEP_ALIVE". Utile pour surveiller la santé/batterie d'une borne sans usage.

{
  "eventType": "KEEP_ALIVE",
  "timestamp": "2026-06-12T08:37:34.000Z",
  "account": { "name": "EP_1" },
  "tracker": { "model": "TAQTONE", "slug": "867280060944991", "batteryLevel": 64 },
  "data": null,            // ← aucune donnée métier
  "site": null,
  "alert": null,
  "ubiqodValidity": { "onSite": true, "badgeSwiped": false, "codeValid": false }
}

Événements WAKE_UP

Le WAKE_UP est la première donnée envoyée à la mise sous tension de la borne ou lors d'un redémarrage (reboot). Comme le KEEP_ALIVE, il porte data: null et ne contient aucune donnée métier : il sert à savoir qu'une borne vient de démarrer (utile pour le suivi de parc, par exemple après un changement de piles ou une réinstallation).

{
  "eventType": "WAKE_UP",
  "timestamp": "2026-06-03T14:09:40.000Z",
  "account": { "name": "Taqt" },
  "tracker": {
    "id": "c62c17ce-b163-4c11-ad52-5ff3a1b90945",
    "label": "TaqtOne Satisfaction",
    "slug": "867280060944991",
    "type": "IOT",
    "model": "TAQTONE",
    "batteryLevel": 75,
    "externalReferences": {}
  },
  "site": null,
  "location": "",
  "data": null,            // ← aucune donnée métier
  "alert": null,
  "ubiqodValidity": { "onSite": true, "badgeSwiped": false, "codeValid": false, "codeFromCookie": false, "scanToken": false, "withPhoto": false }
}

Note : KEEP_ALIVE et WAKE_UP sont regroupés dans une même option du connecteur (voir §1) et partagent la même structure (data: null). Distinguez-les via eventType : KEEP_ALIVE = signal périodique, WAKE_UP = démarrage/redémarrage.

Si votre connecteur n'est pas configuré pour les KEEP_ALIVE, la plateforme les marque status: "filtered" et ne les transmet pas. Activez-les dans les options avancées du connecteur si vous voulez les recevoir.

8. Réponse du serveur (onglet « Réponse du serveur »)

Pour chaque envoi, Ubiqod affiche dans la traçabilité deux onglets : Payload (ce qui a été envoyé, décrit dans les sections précédentes) et Réponse du serveur (ce que votre endpoint a renvoyé à Ubiqod). Cet onglet est un outil de debug : il vous permet de vérifier qu'Ubiqod a bien atteint votre système et comment celui-ci a répondu.

La réponse est un objet JSON contenant le code de statut HTTP retourné par votre serveur, et parfois un corps de réponse :

{
  "statusCode": 200,        // code HTTP renvoyé par VOTRE endpoint
  "body": "..."             // corps de la réponse (optionnel, selon votre serveur)
}

Comment interpréter le code de statut

• 2XX (200, 201, 204…) → succès. Ubiqod considère la donnée comme correctement remise. C'est ce que votre endpoint doit toujours renvoyer après réception, même si le traitement métier est asynchrone.
• Tout autre code (4XX, 5XX) ou absence de réponse → échec de remise. Ubiqod applique alors sa politique de rejeu : une nouvelle tentative automatique après 60 secondes. Si la seconde tentative échoue à son tour, une erreur est journalisée dans les logs du connecteur (et une alerte e-mail peut être configurée dans les paramètres du compte).
• body → texte libre renvoyé par votre système. Purement informatif pour le debug ; il n'a pas vocation à être interprété automatiquement et son contenu dépend entièrement du système de destination.

💡 Recommandation. Renvoyez systématiquement un code 2XX dès la bonne réception du webhook, et déportez votre traitement métier (validation, enregistrement) en arrière-plan. Cela évite les rejeux inutiles et les fausses erreurs dans la traçabilité Ubiqod.

9. Points d'attention pour un contrat d'interface robuste

1. Basez votre logique métier sur data.reference (numéro de bouton), pas sur data.label (qui est un texte renommable).
2. Traitez data.rate comme le marqueur exclusif de la Satisfaction : présent ⇒ note, absent ⇒ événement bouton/badge.
3. Gérez systématiquement les null : data (KEEP_ALIVE), site, data.code (pas de badge), data.photo.
4. Distinguez bouton et badge : data.reference/data.label = le bouton ; data.code = la personne/badge.
5. Utilisez codeValid pour interpréter code.label (nom si true, UID si false).
6. Identifiez les bornes par tracker.id (UUID stable) plutôt que par label ou slug.
7. Convertissez timestamp depuis l'UTC vers le fuseau de l'utilisateur.
8. Répondez en HTTP 2XX : en l'absence de 2XX, Ubiqod réessaie une fois après 60 s, puis journalise une erreur.
9. Sécurisez l'endpoint via une clé API transmise en en-tête (paramètres d'en-tête du connecteur).

10. Tableau récapitulatif — reconnaître chaque type

*Selon configuration : un badge peut ou non accompagner l'appui.

Ressources Ubiqod

• Exemple de payload officiel : https://storage.googleapis.com/skiply-prod-ubiqod/schemas/callbackexample_new.json
• JSON Schema des payloads de données : https://storage.googleapis.com/skiply-prod-ubiqod/schemas/ubiqodhook_new.json
• Configurer le webhook : https://help.taqt.com/portal/fr/kb/articles/récupération-des-événements-et-données-sur-ubiqod-le-webhook
• Notion de connecteur : https://help.taqt.com/portal/fr/kb/articles/qu-est-ce-qu-un-connecteur-dans-ubiqod
• Notice utilisateur TaqtOne : https://help.taqt.com/portal/fr/kb/articles/notice-utilisateur-taqtone