1. Reminder: what the webhook sends

When a TaqtOne device emits valid data, Ubiqod calls your destination URL with an HTTP POST. The request body (the payload) is a JSON object describing the event.

There are three payload families (see connector configuration):

1. DATA — a button press and/or a badge swipe. This is the main business event.
2. KEEP_ALIVE + WAKE_UP — the KeepAlive is the life signal sent daily, even when the device is not used. The WakeUp is the first data sent when the device is first powered on or after a restart (reboot).
3. ALERT — triggered when a threshold programmed in the device is reached.

By default, only DATA payloads are sent. The others can be enabled in the connector's advanced options.

Choosing which event types are transmitted

In the connector's Advanced options tab, the "Select the event types to send" menu determines what flows through this webhook. The available combinations are:

• DATA — data events only
• ALERT — alert events only
• KEEP_ALIVE + WAKE_UP — life and wake-up events only
• DATA + ALERT — data and alert events
• DATA + ALERT + KEEP_ALIVE + WAKE_UP — all event types

Two architecture approaches are possible depending on your preference:

• A single webhook for everything: one endpoint receives all types. Simpler to set up; your code must then route based on eventType to dispatch each message.
• One endpoint per type: you create a separate webhook (hence a separate endpoint) per family — for example one for DATA, one for ALERT, one for KEEP_ALIVE + WAKE_UP. Splitting is cleaner for debugging and separation of concerns, at the cost of maintaining several endpoints.

There is no universal right answer: the choice depends on your system's architecture.

2. Structure common to all events

All payloads share the same envelope. Only the data block changes depending on the device type and the action.

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

  "tracker": {                          // the physical device that emitted the event
    "id": "65413734-a5c6-4165-b445-af6475602586", // stable Ubiqod UUID
    "slug": "865456056209578",          // hardware identifier (IMEI/serial number)
    "type": "IOT",
    "model": "TAQTONE",
    "label": "Aéroport | P2 Sous sol H", // name given to the device
    "batteryLevel": 49,                 // battery % (0–100)
    "externalReferences": {}            // your business keys (ERP/CRM mapping)
  },

  "site": { /* … or null */ },          // linked site (see §6)
  "location": "43.6668227,7.2098445",   // "lat,lng" or "" if not geolocated
  "alert": null,                        // alert block (non-null only for ALERT)
  "data": { /* … or null */ },          // action details (non-null for DATA eventType only)
  "ubiqodValidity": { /* … */ }         // validity flags (see §5)
}

Identification fields to remember for your contract

3. The two main natures of DATA events

A DATA event from a TaqtOne boils down to two signals, which can be combined:

• A button press → described by data.reference (button number) + data.label (configured label).
• A badge swipe → described by the data.code block (badge) + ubiqodValidity.badgeSwiped = true.

It is the combination of these two signals, and above all the button number (data.reference), that gives the business meaning.

The payload does not contain a "device type" field: the type (Satisfaction, Time Tracking, Traceability, Service Request, Custom) results from the device configuration, which you translate through the button mapping.

data block — field reference

data.code block (the badge), present only if a badge was swiped:

💡 Key rule about the badge. The ubiqodValidity.codeValid flag indicates whether the badge is recognized:

• codeValid = true → code.label = person's name (badge registered in a badge list).

• codeValid = false → code.label = UID (unregistered badge). The badge still works, but remains anonymous.

4. Identifying the device type from the payload

The only structurally distinguishable type is Satisfaction. All other types (Time Tracking, Traceability, Service Request, Custom) share the same "button + badge" structure and differ only through the button mapping you configure.

┌─────────────────────────────────────────────┐
│  Is data.rate a number?                      │
└───────────────┬───────────────┬─────────────┘
           YES  │               │  NO
                ▼               ▼
       ┌────────────────┐  ┌──────────────────────────────┐
       │  SATISFACTION  │  │  "Button + badge" event       │
       │ (code = null,  │  │  → meaning given by           │
       │  badgeSwiped   │  │     data.reference (button)   │
       │  = false)      │  │     + badgeSwiped / code      │
       └────────────────┘  └──────────────────────────────┘

data.reference is the stable key: a physical button keeps its number. data.label reflects your configuration and can be renamed — use it for display, but base your logic on reference.

4.1 Satisfaction (smiley buttons)

A satisfaction device emits a rating, without a badge.

Signature: data.rate present · data.code = null · ubiqodValidity.badgeSwiped = false.

The rate field is normalized (scale of 1 to 5, 5 being the best possible satisfaction rating), regardless of the number of physical smileys. The label gives the associated text.

Note: Satisfaction devices are also commonly used in addition for traceability (badging). See section 4.3.

Observed examples (3-smiley configuration):

// Satisfaction — "Excellent" rating
{
  "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",        // "green smiley" button
    "label": "Excellent",    // Customizable field in "interface"
    "rate": 5,               // ← normalized rating 1–5 (present = satisfaction)
    "email": "",
    "code": null,            // ← no badge
    "pressCount": 4,         // 4 presses received on this button
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": false, "codeValid": false, "onSite": true }
}

4.2 Time Tracking (Check-in / Check-out buttons)

An agent swipes a badge then presses a "Check-in" or "Check-out" button. The event combines button + badge.

Signature: data.code present · badgeSwiped = true · no rate · the button's label/reference carries the check-in/check-out semantics.

// Time tracking — departure from 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",                 // ← "Check-out" button
    "label": "Departure from site",
    "code": {
      "reference": "045C723A521E90",  // badge UID
      "label": "Damaris Rubeta"      // name (known badge → codeValid:true)
    },
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": true, "codeValid": true, "onSite": true }
}

The "check-in" or "check-out" meaning depends on the button (reference/label): there is no dedicated time-tracking field. Base your logic on the device's button mapping.

As a general rule, button "3" is dedicated to check-in and button "5" to check-out.

4.3 Traceability (badging only)

The traceability device has no button: you simply swipe a badge to prove a visit. The determining signal is therefore the badge.

Signature: data.code present · badgeSwiped = true. The button (reference/label) corresponds to the default configured passage.

// Traceability / badged passage (unregistered badge → 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", // badge UID
      "label": "04549102C31B90"      // = UID because unknown badge (codeValid:false)
    },
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": true, "codeValid": false, "onSite": true }
}

4.4 Service Request (intervention request buttons)

One or more buttons trigger an intervention request (e.g. "consumable replacement", "cleaning"). The meaning comes from the button (reference/label).

The badge is optional: a request can be made by a simple press (without a badge), and an agent can later close the intervention by pressing the same button with their badge (see the two-step case below).

Signature: no rate; the label/reference identifies the request type; code / badgeSwiped present when a badge accompanies the press (typically closure by a service agent).

// Service request — service entry
{
  "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",                       // ← "intervention request" button
    "label": "Demande intervention",
    "code": { "reference": "26167181000000", "label": "26167181000000" },
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": true, "codeValid": false, "onSite": true }
}

Two-step case: request then closure on the same button

The same Service Request button can be used both to open a request and then to close it. The only element distinguishing the two events is the presence of the badge (code / badgeSwiped).

1. Opening the request — a user reports a need (here a consumable replacement, button 4), without badging:

// Service Request — opening a request (press only, no 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",        // ← "consumable replacement" button
    "label": "Savon",        // configured label ("soap")
    "code": null,            // ← no badge: this is a REQUEST
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": false, "codeValid": false, "onSite": true }
}

2. Closure / completion — later, an agent performs the intervention and presses the same button 4 + badge; the badge identifies the agent:

// Service Request — closure (same button + agent's badge)
{
  "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",        // ← same button
    "label": "Savon",
    "code": {
      "reference": "04405902C31B90",
      "label": "Marin Fecha",      // agent (known badge → codeValid:true)
      "externalReferences": { "Category": "Cleaning" }
    },
    "pressCount": 1,
    "photo": null
  },
  "ubiqodValidity": { "badgeSwiped": true, "codeValid": true, "onSite": true }
}

💡 Integration side: for this scenario, track the state of a request per button (reference). An event without a badge = opening/request; an event with a badge on the same button = closure, with the agent in code.

4.5 Custom (mix of the previous cases)

A Custom device combines several functions on distinct buttons (e.g. 2 smiley buttons + 3 service request buttons + badging). There is nothing special to detect in the payload: each press produces a standard event, and it is your reference → meaning mapping table that distinguishes the functions.

Practical routing rule in code:

if data.rate is present            → treat as SATISFACTION (rating = data.rate)
otherwise, based on data.reference (button):
    └─ apply the mapping configured for this device
       (Check-in / Check-out / Intervention X / Passage …)
and in all cases, if data.code != null and badgeSwiped == true:
    └─ attach the event to a badge / a person
       (name if codeValid, otherwise anonymous UID)

5. The ubiqodValidity block (validity flags)

These booleans qualify the event. The two most useful for your logic are badgeSwiped and codeValid.

6. The site and account blocks

• account.name: the name of your Ubiqod organization. Constant for a given account.
• site: the site linked to the device. Can be null if the device is not linked to a site. When present:

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

Never assume that site is present: handle the null case. To link a site reliably on the integration side, prefer site.id (or site.externalReferences) over site.label.

7. KEEP_ALIVE events

Periodic life signal. data is null and eventType = "KEEP_ALIVE". Useful for monitoring the health/battery of a device without usage.

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

WAKE_UP events

The WAKE_UP is the first data sent when the device is powered on or after a restart (reboot). Like the KEEP_ALIVE, it carries data: null and contains no business data: it lets you know that a device has just started (useful for fleet monitoring, for example after a battery change or a reinstallation).

{
  "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,            // ← no business data
  "alert": null,
  "ubiqodValidity": { "onSite": true, "badgeSwiped": false, "codeValid": false, "codeFromCookie": false, "scanToken": false, "withPhoto": false }
}

Note: KEEP_ALIVE and WAKE_UP are grouped under the same connector option (see §1) and share the same structure (data: null). Distinguish them via eventType: KEEP_ALIVE = periodic signal, WAKE_UP = startup/restart.

If your connector is not configured for KEEP_ALIVE events, the platform marks them status: "filtered" and does not transmit them. Enable them in the connector's advanced options if you want to receive them.

8. Server response ("Server response" tab)

For each delivery, Ubiqod displays two tabs in the traceability view: Payload (what was sent, described in the previous sections) and Server response (what your endpoint returned to Ubiqod). This tab is a debugging tool: it lets you check that Ubiqod actually reached your system and how it responded.

The response is a JSON object containing the HTTP status code returned by your server, and sometimes a response body:

{
  "statusCode": 200,        // HTTP code returned by YOUR endpoint
  "body": "..."             // response body (optional, depending on your server)
}

How to interpret the status code

• 2XX (200, 201, 204…) → success. Ubiqod considers the data as correctly delivered. This is what your endpoint should always return upon receipt, even if the business processing is asynchronous.
• Any other code (4XX, 5XX) or no response → delivery failure. Ubiqod then applies its retry policy: an automatic new attempt after 60 seconds. If the second attempt also fails, an error is logged in the connector logs (and an e-mail alert can be configured in the account settings).
• body → free text returned by your system. Purely informative for debugging; it is not meant to be interpreted automatically and its content depends entirely on the destination system.

💡 Recommendation. Always return a 2XX code as soon as the webhook is received, and defer your business processing (validation, storage) to the background. This avoids unnecessary retries and false errors in the Ubiqod traceability view.

9. Key points for a robust interface contract

1. Base your business logic on data.reference (button number), not on data.label (which is renamable text).
2. Treat data.rate as the exclusive marker of Satisfaction: present ⇒ rating, absent ⇒ button/badge event.
3. Systematically handle null values: data (KEEP_ALIVE), site, data.code (no badge), data.photo.
4. Distinguish button from badge: data.reference/data.label = the button; data.code = the person/badge.
5. Use codeValid to interpret code.label (name if true, UID if false).
6. Identify devices by tracker.id (stable UUID) rather than by label or slug.
7. Convert timestamp from UTC to the user's time zone.
8. Respond with HTTP 2XX: without a 2XX, Ubiqod retries once after 60 s, then logs an error.
9. Secure the endpoint with an API key passed as a header (connector header parameters).

10. Summary table — recognizing each type

*Depending on configuration: a badge may or may not accompany the press.

Ubiqod resources

• Official payload example: https://storage.googleapis.com/skiply-prod-ubiqod/schemas/callbackexample_new.json
• JSON Schema of data payloads: https://storage.googleapis.com/skiply-prod-ubiqod/schemas/ubiqodhook_new.json
• Configuring the webhook: https://help.taqt.com/portal/fr/kb/articles/récupération-des-événements-et-données-sur-ubiqod-le-webhook
• What is a connector: https://help.taqt.com/portal/fr/kb/articles/qu-est-ce-qu-un-connecteur-dans-ubiqod
• TaqtOne user manual: https://help.taqt.com/portal/fr/kb/articles/notice-utilisateur-taqtone