Logo Neyos
Intégrer Neyos à mes outils

Configurer un webhook

Les webhooks permettent de rediriger automatiquement les messages générés par vos balises vers vos propres systèmes via HTTP POST. Ils transmettent des données brutes (position, événements, état système) au format JSON, prêtes à être exploitées dans vos applications métiers.

Principes de fonctionnement

Chaque fois qu’un message est généré par une balise, il est encapsulé dans une trame JSON standardisée. Cette trame contient toujours le même socle d’informations (horodatage, réseau, batterie, etc.), auquel s’ajoutent les éléments métier (points GPS, événements, configurations…).

Configuration pas à pas

La configuration des webhooks se fait directement depuis l’interface Neyos (onglet Webhooks). Voici la procédure type :

  1. Connectez-vous à la plateforme Neyos.
  2. Accédez à l’onglet Webhook
  3. Cliquez sur .
  4. Indiquez l’URL cible de votre serveur, et cliquez sur Activé
  5. Votre webhook est maintenant en marche, les données sont redirigées vers le endpoint enregistré.

Information visibles pour chaque webhook

  • Statut d’activation (Enabled / Disabled)
  • Type d’événements écoutés
  • Statut HTTP renvoyé par votre serveur (200, 400, 500…)
  • Temps de réponse moyen du serveur
  • Date et type du dernier envoi

Structuration du JSON

Header

L’en-tête regroupe les métadonnées du message : son type (message.created), l’identifiant unique, le type de contenu (datas, logs), ainsi que la date de réception. Ces informations permettent d’identifier et tracer chaque message.

{
  "id": "msg_2xcsTDBIyBYJl6OWNfGbAPwHc0w",
  "type": "datas",
  "network": "gsm",
  "mcc": 208,
  "mnc": 20,
  "rsrq": 100,
  "battery": 51,
  "temperature": 20,
  "receivedAt": "2025-05-26T08:38:21.419+00:00"
}

Elements

Le corps du message porte le contexte réseau (mcc/mnc, opérateur, batterie, température, qualité radio) ainsi que la liste des éléments (elements). C’est ici que se trouvent les données exploitables.

Les éléments représentent la donnée utile issue du terrain. Il peut s’agir :

  • d’un Point GPS, avec coordonnées, altitude, vitesse et qualité de fix.
  • d’un Événement, tel qu’un appui bouton, une mise en veille, une chute détectée.
  • d’une Configuration appliquée à la balise.
  • d’un Log, utile pour le diagnostic.

Type "point"

Représente une position GPS et inclut les coordonnées, l'altitude, la vitesse et la validité du fix GPS.

{
  "id": "elm_2xcsTFii339xmrqOz71ReQAGi0k",
  "type": "point",
  "datas": {
    "latitude": 13.82172,
    "longitude": -7.94417,
    "timestamp": 1748248697,
    "altitude": 1180,
    "speed": 0,
    "validity": {
      "fixOK": false
    }
  }
}

Type "event"

{
  "id": "elm_2xcsTHQGGc5GnUPCuJ2R26NiMmz",
  "type": "event",
  "datas": {
    "latitude": 13.8027,
    "longitude": -7.93776,
    "timestamp": 1748248700,
    "altitude": 1176,
    "speed": 0,
    "validity": {
      "fixOK": false
    },
    "code": 920,
    "eventType": "button_3"
  }
}

Footer

Enfin, le bas de la trame rassemble le contexte opérateur et tracker. Ces champs facilitent le diagnostic ou l’agrégation : vous savez immédiatement quelle balise a généré le message et par quel réseau.

{
  "networkOperator": {
    "mcc": 208,
    "mnc": 20,
    "region": "Europe",
    "country": "France",
    "iso": "FR",
    "operator": "Bouygues Telecom",
    "brand": "Bouygues"
  },
  "tracker": {
    "id": "tra_2vDzuf37SnBKlM9nq6P9jOz3kx7",
    "serial": "03436",
    "alias": null,
    "createdAt": "2025-04-03T15:37:36.160+00:00",
    "updatedAt": "2025-05-26T08:38:21.430+00:00"
  }
}

Exemple de trame JSON

Une fois tous ces éléments mis en forme, voici un exemple de trame complète telle qu’elle est reçue par un webhook.

{
  "type": "message.created",
  "data": {
    "id": "msg_33XXsFGm5F4WGFeX1dQGO8hcvRx",
    "type": "datas",
    "network": "gsm",
    "mcc": 302,
    "mnc": 72,
    "rsrq": 68,
    "battery": 6,
    "temperature": 28,
    "receivedAt": "2025-10-03T04:09:55.638+00:00",
    "elements": [
      {
        "id": "elm_33XXsH9VdDxY17veBYAjASPr0PC",
        "type": "point",
        "datas": {
          "latitude": 45.471494,
          "longitude": -73.418698,
          "timestamp": 1759464594,
          "altitude": 38,
          "speed": 4,
          "validity": {
            "dateValid": false,
            "todValid": false,
            "fixOK": true,
            "llhValid": true,
            "fixType": 3
          },
          "highAccuracyRaw": "04080003",
          "highAccuracy": {
            "1": "4",
            "2": "8",
            "3": "0",
            "4": "3"
          },
          "highAccuracyDecoded": {
            "lat": 4,
            "lng": 8,
            "millis": 3
          },
          "orginalLatitude": 45.47149,
          "latitudeHighAccuracy": 45.471494,
          "orginalLongitude": -73.41869,
          "longitudeHighAccuracy": -73.418698,
          "timestampHighAccuracy": 1759464594.3
        },
        "messageId": "msg_33XXsFGm5F4WGFeX1dQGO8hcvRx",
        "createdAt": "2025-10-03T04:09:55.642+00:00"
      }
    ],
    "networkOperator": {
      "mcc": 302,
      "mnc": 72,
      "region": "Amérique du Nord",
      "country": "Canada",
      "iso": "CA",
      "operator": "Rogers",
      "brand": "Rogers"
    },
    "tracker": {
      "id": "tra_2zMrxQ8aHDDmw0VfwoR3byi0jfX",
      "serial": "06158",
      "alias": "4004",
      "createdAt": "2025-07-03T14:13:48.842+00:00",
      "updatedAt": "2025-10-03T04:09:25.670+00:00",
      "network": "gsm",
      "battery": 6,
      "temperature": 28,
      "mcc": 302,
      "mnc": 72,
      "rsrq": 68,
      "connected": true,
      "connectedAt": "2025-10-01T13:05:16.224+00:00",
      "sleep": true,
      "sleepAt": "2025-10-02T12:52:39.347+00:00",
      "charging": false,
      "chargingAt": null,
      "sentAt": "2025-10-03T04:09:25.659+00:00",
      "lastPointAt": "2025-10-03T04:09:24.000+00:00",
      "latitude": "45.471538",
      "longitude": "-73.418938",
      "altitude": 46,
      "speed": 2,
      "configSentAt": "2025-10-03T02:46:07.363+00:00",
      "customerId": "cus_2yUvqgD1ewDnpZ6BmDN13Bi75vC"
    }
  }
}

Suivi et Diagnostic

L’onglet Webhooks de la plateforme vous permet de suivre en temps réel l’état de vos intégrations (statut, codes HTTP, latence, logs). Cela facilite le débogage et garantit la fiabilité des échanges. Dans l’interface Neyos, chaque webhook affiche :

  • Succès ou échec des envois (statut HTTP renvoyé).
  • Latence de traitement côté serveur client.
  • Nombre d’événements envoyés sur une période donnée.
Si votre serveur ne répond pas correctement (erreur HTTP persistante), les messages ne sont pas rejoués. Veillez à surveiller vos webhooks régulièrement.

Bonnes pratiques

Pour garantir une intégration robuste, nous recommandons :

  • Sécurisez votre URL (HTTPS obligatoire, filtrage IP recommandé).
  • Vérifiez la charge : en cas de fort trafic, assurez-vous que votre infrastructure peut absorber les envois.
  • Traitez les messages en asynchrone pour éviter de ralentir la réception.
  • Archivez les logs pour faciliter le support et le diagnostic.

Introduction

Découvrez comment intégrer les données de vos balises Neyos dans vos outils métiers grâce aux webhooks et à l’API Neyos.

API Neyos

Une API REST sécurisée pour interagir avec vos balises, automatiser vos intégrations et enrichir vos outils métier.