Recevoir les événements Wogeez par webhook

Un webhook inverse le sens habituel de l'API. Au lieu d'interroger Wogeez à intervalle régulier, vous lui donnez une adresse, et c'est lui qui l'appelle quand un événement se produit. Chaque appel est une requête POST avec un corps JSON.

Il existe deux familles de webhooks. Les webhooks d'entreprise se déclarent par l'API et concernent tout le parc. Les webhooks de scénario se déclarent dans le scénario et se déclenchent à la fin de chaque parcours client.

Pour un premier essai, un service d'inspection de requêtes comme webhook.site vous donne une adresse temporaire et affiche chaque appel reçu. Pour la suite, votre point de réception doit répondre avec un code 2xx en moins de 30 secondes. Répondez tout de suite, puis traitez le message en arrière-plan.

Voici un récepteur minimal en Node.js. Il vérifie le secret partagé, que vous choisirez plus loin, puis traite les deux familles: un message de scénario porte un champ context, un message d'état de santé n'en a pas.

import express from "express";

const app = express();
app.use(express.json({ limit: "2mb" }));

app.post("/wogeez", (req, res) => {
  if (req.get("X-Wogeez-Secret") !== process.env.WOGEEZ_SECRET) {
    return res.sendStatus(401);
  }
  res.sendStatus(204); // répondre d'abord

  if (req.body.context) {
    const { mission, deviceID } = req.body.context.id;
    const success = req.body.context.steps.every((step) => step.success);
    console.log(mission, deviceID, success ? "réussi" : "en échec");
    return;
  }

  const health = JSON.parse(req.body.payload);
  for (const hub of health.hubs ?? []) {
    for (const device of hub.devices ?? []) {
      console.log(hub.label, device.label, device.health?.state);
    }
  }
});

app.listen(3000);

Choisissez un secret, une longue chaîne aléatoire, et transmettez-le dans un en-tête personnalisé. Wogeez l'ajoutera à chaque appel, ce qui permet à votre serveur de vérifier que la requête vient bien de lui.

curl -s -X POST "https://api-v2.wogeez.com/companies/$COMPANY/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ON_RESOURCE_DEVICE_HEALTH",
    "url": "https://exemple.fr/wogeez",
    "method": "POST",
    "headers": { "X-Wogeez-Secret": "votre-secret" },
    "description": "Supervision du parc"
  }'

La réponse contient l'identifiant du webhook, à garder pour le supprimer plus tard.

{
  "item": {
    "id": "5f0c2a7e-...",
    "type": "ON_RESOURCE_DEVICE_HEALTH",
    "url": "https://exemple.fr/wogeez",
    "method": "POST",
    "headers": { "X-Wogeez-Secret": "votre-secret" },
    "description": "Supervision du parc",
    "createdAt": "2026-10-06T10:42:00"
  }
}

Le corps de chaque appel contient un seul champ, payload. Attention, sa valeur est une chaîne de caractères qui contient elle-même du JSON: décodez-la une seconde fois.

{
  "payload": "{\"updated\":\"2026-10-06T10:45:12\",\"hubs\":[...]}"
}

Une fois décodé, l'état de santé décrit les hubs de la borne puis leurs équipements, chacun avec son état. Voici un exemple raccourci, avec une imprimante qui arrive en fin de papier.

{
  "updated": "2026-10-06T10:45:12",
  "hubs": [
    {
      "uid": "...",
      "label": "Wogeez Engine",
      "version": "1.0.0",
      "devices": [
        {
          "uid": "...",
          "label": "Imprimante",
          "health": {
            "state": "WARNING",
            "message": "Fin de rouleau proche"
          }
        }
      ]
    }
  ]
}

Avec jq, la même lecture tient en une ligne.

jq '.payload | fromjson | .hubs[].devices[] | { label, state: .health.state }'

L'état d'un équipement prend l'une de ces valeurs: NOMINAL quand il fonctionne, WARNING en cas d'avertissement, DOWN quand il est en panne, BOOTING pendant son démarrage et HIBERNATION en veille. Savoir si tout va bien

Un webhook de scénario se décrit dans le scénario, sous forme de tâche de fond, dans la liste tasks du fichier scenario.json. Chaque tâche indique ses déclencheurs, réussite, échec ou les deux, puis l'appel à faire. Il s'applique ensuite à chaque passage, sur toutes les bornes où cette version du scénario est déployée.

"tasks": [
  {
    "id": "fin-de-parcours",
    "description": "Prévenir notre système de caisse",
    "triggers": [
      { "type": "ON_SCENARIO_END_IN_SUCCESS", "content": {} },
      { "type": "ON_SCENARIO_END_IN_FAILURE", "content": {} }
    ],
    "steps": [
      {
        "id": "appel-caisse",
        "description": "Envoi du passage à la caisse",
        "type": "WEB_HOOK",
        "content": {
          "url": "https://exemple.fr/wogeez",
          "method": "POST",
          "payload": "{\"source\": \"borne\"}",
          "headers": { "X-Wogeez-Secret": "votre-secret" }
        }
      }
    ]
  }
]

Le parcours est réussi quand toutes les étapes jouées ont réussi. Une seule étape en échec, comme un paiement refusé ou une impression impossible, le fait passer en échec. Le champ payload est une chaîne libre, renvoyée telle quelle: utilisez-la pour transmettre une information fixe à votre serveur.

L'appel part quand Wogeez reçoit le résumé du passage, c'est-à-dire à la fin du parcours dès que la borne est connectée. Une borne restée hors ligne envoie ses passages à son retour.

Le corps contient le contexte du passage et le payload défini dans la tâche. Le contexte réunit les identifiants du passage, chaque étape jouée avec sa réussite et ses productions, comme les saisies d'un formulaire ou le résultat d'un paiement.

{
  "context": {
    "id": {
      "correlation": "...-hidden-camel",
      "mission": "hidden-camel",
      "companyID": "d013e5cb-...",
      "scenarioID": "5634bdf4-...",
      "scenarioVersionID": "30d5b095-...",
      "deviceID": "..."
    },
    "steps": [
      {
        "id": { "id": "etape-formulaire" },
        "success": true,
        "productions": [
          {
            "type": "FORM",
            "success": true,
            "inputs": { "firstname": "Camille" }
          }
        ]
      }
    ]
  },
  "payload": "{\"source\": \"borne\"}"
}

Le numéro de mission, ici hidden-camel, est celui que le client peut lire à l'écran ou sur son ticket. Gardez-le avec vos données: il permet de retrouver le passage dans le manager et de le relier à une demande du support. Le même contexte reste consultable plus tard par l'API des snapshots, décrite dans le Swagger.

• Vérifiez le secret à chaque appel et refusez ceux qui ne le portent pas. Gardez-le hors de votre code, dans une variable d'environnement.
• Répondez vite. Un appel sans réponse 2xx en 30 secondes est considéré en échec et renvoyé, jusqu'à 5 tentatives en tout.
• Attendez-vous à des répétitions. Une même borne envoie son état régulièrement, même quand rien n'a changé, et une nouvelle tentative peut renvoyer un message déjà reçu. Comparez l'état reçu au précédent avant d'ouvrir un ticket, et utilisez la corrélation d'un passage pour ne pas le traiter deux fois.
• Utilisez HTTPS, pour que le secret et l'état du parc ne circulent jamais en clair.

La liste des webhooks de l'entreprise peut être filtrée par type d'événement.

curl -s "https://api-v2.wogeez.com/companies/$COMPANY/webhooks?type=ON_RESOURCE_DEVICE_HEALTH" \
  -H "Authorization: Bearer $TOKEN" | jq '.items[] | { id, url, description }'

Pour arrêter les appels, supprimez le webhook avec son identifiant. L'API répond 204.

curl -s -X DELETE "https://api-v2.wogeez.com/companies/$COMPANY/webhooks/5f0c2a7e-..." \
  -H "Authorization: Bearer $TOKEN"

Le détail des points d'accès se trouve dans le Swagger. Les webhooks de scénario, eux, se retirent en modifiant le scénario puis en déployant sa nouvelle version.