Webhooks

Un webhook, c'est une notification automatique. Quand quelque chose se produit dans votre espace Workbots, par exemple la création d'un apprenant, Workbots envoie aussitôt un message à l'adresse web de votre choix. Votre outil reçoit l'information sans que personne ait à la ressaisir.

Les webhooks sont en cours de déploiement. L'interface est visible sous Paramètres → Développeur → Webhooks. Cette page décrit ce que vous y voyez.

Comment ça marche

Le principe tient en quatre temps.

Vous donnez une adresse à Workbots

Cette adresse s'appelle un endpoint. C'est une URL de votre serveur, ou une URL fournie par un outil comme Make ou Zapier. Elle ressemble à https://hooks.mon-of.fr/workbots.

Vous choisissez les événements qui vous intéressent

Vous n'êtes pas obligé de tout recevoir. Un endpoint peut n'écouter qu'un seul événement, comme apprenant.created, ou plusieurs à la fois.

Workbots appelle votre adresse

Dès que l'événement se produit, Workbots envoie une requête HTTP POST à votre endpoint, avec les informations de l'objet concerné au format JSON.

Votre serveur répond

Votre serveur doit répondre rapidement avec un code de succès (200 ou 204). Toute autre réponse est considérée comme un échec, et la livraison est réessayée.

Capture à venir

La section Webhooks dans Paramètres → Développeur

Créer un endpoint

Depuis Paramètres → Développeur → Webhooks, cliquez sur Ajouter un endpoint, puis renseignez :

L'URL de votre serveur. Elle doit être publique et accessible en HTTPS.
Les événements à écouter. Cochez ceux dont vous avez besoin.

Une fois l'endpoint créé, il apparaît dans le tableau, avec quatre colonnes.

Colonne	Ce qu'elle affiche
URL	L'adresse appelée, avec l'identifiant de l'endpoint en dessous
Événements	Les événements écoutés. Au-delà de deux, un compteur indique le reste
Statut	Actif, En échec ou En pause
Dernière livraison	Le temps écoulé depuis le dernier envoi

Les trois statuts

Statut	Ce qu'il signifie
Actif	L'endpoint fonctionne, les dernières livraisons ont réussi
En échec	Plusieurs livraisons récentes ont renvoyé une erreur
En pause	L'endpoint ne reçoit plus aucun événement, vous l'avez suspendu

Le menu d'actions, à droite de chaque ligne, propose Modifier, Mettre en pause (ou Reprendre) et Supprimer.

Mettez un endpoint en pause plutôt que de le supprimer quand vous intervenez sur votre serveur. Vous le reprendrez ensuite sans avoir à le recréer.

Les événements disponibles

Les événements portent sur vos sept bases de données. Le nom suit toujours la forme objet.action.

Base	Événements
Apprenants	`apprenant.created`, `apprenant.updated`
Entreprises	`entreprise.created`, `entreprise.updated`
Intervenants	`intervenant.created`, `intervenant.updated`
Lieux	`lieu.created`, `lieu.updated`
Financeurs	`financeur.created`, `financeur.updated`
Établissements	`etablissement.created`, `etablissement.updated`
Maîtres d'apprentissage	`maitre_apprentissage.created`, `maitre_apprentissage.updated`

Le contenu d'un message

Chaque livraison transporte un objet JSON. Il contient l'identifiant de l'événement, son type, sa date, et les données de l'objet concerné.

{
  "id": "evt_01HRX2",
  "type": "apprenant.created",
  "createdAt": "2026-07-13T12:48:21Z",
  "data": {
    "id": "obj_4F2k",
    "organizationId": "org_workbots"
  }
}

Champ	Ce qu'il contient
`id`	L'identifiant unique de l'événement, utile pour éviter les doublons
`type`	Le nom de l'événement, par exemple `apprenant.created`
`createdAt`	La date et l'heure de l'événement, au format ISO 8601 en UTC
`data`	Les données de l'objet concerné, dont son identifiant et celui de votre organisme

Enregistrez l'id de chaque événement traité. Si la même livraison vous parvient deux fois, à la suite d'un réessai par exemple, vous saurez l'ignorer.

Vérifier la signature

Votre endpoint est une adresse publique. N'importe qui pourrait lui envoyer un faux message en se faisant passer pour Workbots. La signature sert à écarter ce risque.

Workbots ajoute à chaque requête un en-tête Workbots-Signature. Cet en-tête est calculé à partir du contenu du message et d'un secret que vous seul connaissez : la clé de signature.

Où trouver la clé de signature

Elle est affichée en haut de la section Webhooks, sous le libellé Clé de signature. Elle commence par whsec_. Vous pouvez la révéler, la copier, ou la Régénérer.

Si vous régénérez la clé, la précédente reste valable 24 heures. Ce délai vous laisse le temps de déployer la nouvelle clé sur vos serveurs sans interrompre les livraisons. Passé ce délai, l'ancienne clé cesse d'être acceptée.

Comment la vérifier

Le principe : votre serveur recalcule la signature à partir du corps brut de la requête et de votre clé secrète, puis la compare à celle reçue dans l'en-tête. Si les deux correspondent, le message vient bien de Workbots.

import crypto from "crypto";

function verifierSignature(corpsBrut: string, signatureRecue: string, secret: string) {
  const attendue = crypto
    .createHmac("sha256", secret)
    .update(corpsBrut, "utf8")
    .digest("hex");

  // Comparaison à temps constant, pour ne pas fuiter d'information
  return crypto.timingSafeEqual(
    Buffer.from(attendue),
    Buffer.from(signatureRecue),
  );
}

Calculez la signature sur le corps brut de la requête, avant tout traitement JSON. Si vous décodez puis réencodez le JSON, le moindre espace en plus ou en moins change le résultat, et la vérification échoue.

Ne publiez jamais votre clé de signature. Elle ne doit figurer ni dans votre code source versionné, ni dans un ticket, ni dans une capture d'écran. Rangez-la dans une variable d'environnement.

Suivre les livraisons

Sous le tableau des endpoints, le bloc Livraisons récentes liste les envois des dernières 24 heures. Un sélecteur permet d'afficher Toutes les livraisons ou seulement les Échouées.

Chaque ligne affiche l'heure, le nom de l'événement, l'endpoint appelé, le code de réponse HTTP et la durée en millisecondes. Une icône signale les livraisons qui ont fait l'objet d'un réessai.

Code de réponse	Ce qu'il indique
`200`, `204`	Votre serveur a bien reçu et accepté le message
`4xx` (par exemple `429`)	Votre serveur a refusé le message, souvent parce qu'il est saturé
`5xx` (par exemple `502`)	Votre serveur est en erreur ou n'a pas répondu à temps

Capture à venir

Le journal des livraisons récentes, filtré sur les échecs

Rejouer une livraison

Cliquez sur une ligne du journal pour la déplier. Vous y voyez l'identifiant de l'événement, le numéro de la tentative, la durée, ainsi que deux blocs de code : la Requête envoyée par Workbots et la Réponse renvoyée par votre serveur. Chaque bloc peut être copié d'un clic.

Le bouton Renvoyer relance la livraison à l'identique. Utilisez-le quand votre serveur était momentanément indisponible et que vous voulez rattraper l'événement manqué.

Le lien Voir toutes les livraisons, en bas du bloc, ouvre l'historique complet au-delà des dernières 24 heures.

Brancher à Make ou Zapier

Vous n'avez pas besoin d'un serveur pour recevoir un webhook. Les outils d'automatisation en fournissent un.

Créez un scénario dans votre outil

Dans Make, ajoutez un module Webhooks → Custom webhook. Dans Zapier, créez un déclencheur Webhooks by Zapier → Catch Hook.

Copiez l'adresse fournie

L'outil génère une URL, du type https://hook.eu2.make.com/... ou https://hooks.zapier.com/hooks/catch/.... Copiez-la.

Créez l'endpoint dans Workbots

Collez cette URL dans Ajouter un endpoint, puis cochez les événements à écouter.

Déclenchez un événement de test

Créez un apprenant de test dans Workbots. Votre outil reçoit le message et vous montre sa structure. Vous pouvez alors construire la suite du scénario, par exemple l'ajout d'une ligne dans un tableur ou la création d'un contact dans votre CRM.

Vérifiez dans le journal

Revenez dans Livraisons récentes et contrôlez que la livraison affiche bien un code 200.