Webhooks de gestion de projet expliqués par Celoxis : alertes de projet en temps réel, configuration et sécurité

Un webhook Celoxis est une instruction permanente : lorsqu'une action spécifique se produit dans Celoxis, comme la création d'un projet, la modification du statut d'une tâche ou l'approbation d'une dépense, Celoxis envoie automatiquement cette mise à jour à une URL que vous spécifiez. Vous choisissez les actions concernées, vous fournissez un point de terminaison HTTPS, et Celoxis se charge du reste. Personne n'a besoin de se souvenir de transmettre le message, car le système le fait dès que le changement survient.

C'est important car l'alternative, qui consiste à interroger Celoxis en permanence via l'API pour vérifier si des modifications ont été apportées, est lente, consomme inutilement des appels API et laisse un délai entre la modification et sa prise en compte par votre équipe. Un webhook permet de combler ce délai.

Chaque livraison est une requête POST JSON signée. Votre point de terminaison reçoit l'événement, confirme sa provenance de Celoxis, puis effectue l'action : notification d'un canal, création d'un enregistrement CRM, lancement d'un processus de facturation ou envoi de la modification vers un entrepôt de données.

Chaque bureau de gestion de projet (PMO) finit par se heurter au même problème : le système de gestion de projet contient les informations, mais celles-ci doivent être diffusées à cinq autres endroits : un CRM, un canal Slack, un outil comptable et un tableau de bord de veille stratégique. Aucun de ces outils ne consulte Celoxis de manière autonome. Il faut donc que quelqu’un assure cette liaison, et pendant longtemps, cette tâche a été accomplie manuellement par une personne ou par un script interrogeant l’API toutes les soixante secondes dans l’espoir de détecter une nouveauté.

L'interrogation régulière a un coût spécifique et discret. Vous multipliez les appels API pour demander « y a-t-il du nouveau ? » et obtenez une réponse négative la plupart du temps, jusqu'au moment crucial où votre intégration accuse encore jusqu'à une minute de retard. À l'échelle d'un projet unique, c'est acceptable. Mais à l'échelle d'un portefeuille complet, cela se traduit par une infrastructure gaspillée et un système toujours en retard.

Un second problème, plus spécifique, se manifeste dans le secteur des logiciels de gestion de projet. Plusieurs plateformes établies ont conçu leurs systèmes de webhooks selon le principe du « tout ou rien » : s’abonner, c’est recevoir tous les événements, toutes les modifications de cellules, tous les commentaires, même les changements mineurs, mélangés au signal souhaité. Les équipes ont fini par créer leur propre couche de filtrage, juste pour pouvoir jeter la majeure partie des informations reçues. Certains fournisseurs intègrent désormais le filtrage des événements dans des systèmes qui en étaient initialement dépourvus, ce qui témoigne de la fréquence de cette lacune.

Les événements webhook de Celoxis sont définis dès le départ par type d'élément et action. Vous vous abonnez indépendamment aux événements « Ajout de projet », « Mise à jour de tâche » ou « Suppression de dépense », ce qui évite toute adaptation ultérieure. Plus d'informations ci-dessous.

Le mécanisme est simple par conception. Trois étapes se déroulent systématiquement :

1. Une activité est enregistrée dans Celoxis : création d’un projet, mise à jour d’une tâche, saisie de temps ou approbation d’une dépense.
2. Celoxis vérifie votre abonnement. Si votre webhook est configuré pour détecter cette activité spécifique, le processus passe à l'étape trois. Sinon, aucune action n'est entreprise.
3. Celoxis envoie une notification signée à l'URL de votre point de terminaison. Votre système reçoit la mise à jour en temps quasi réel.

Si le point de terminaison est indisponible ou renvoie une erreur, Celoxis ne supprime pas l'événement. Il effectue automatiquement une nouvelle tentative avec un délai d'attente, et vous pouvez également relancer manuellement la livraison depuis l'interface d'administration une fois la destination rétablie. Une livraison est considérée comme réussie lorsque votre point de terminaison renvoie une réponse HTTP 2xx.

Événements auxquels vous pouvez vous inscrire

Chaque webhook détecte d'ajout, de mise à jouret de suppression sur les types d'éléments que vous sélectionnez. Vous n'êtes pas obligé de recevoir toutes les notifications de Celoxis. Vous choisissez celles qui vous intéressent.

Voici quelques exemples concrets de ce à quoi cela ressemble en pratique :

• Un projet est créé et une opportunité CRM apparaît automatiquement.
• Une tâche est ajoutée et le canal Slack approprié est notifié sans que personne n'ait à saisir de message.
• Une dépense est approuvée et la comptabilité est notifiée immédiatement, et non lors de la prochaine synchronisation par lots.
• Le temps est enregistré et un processus de facturation se déclenche automatiquement.

Commencez par un ou deux événements, pas les six. Plus d'événements signifient plus de notifications sur votre terminal, et la plupart des intégrations n'ont besoin que d'une petite partie de l'activité pour bien fonctionner.

À quoi ressemble la charge utile

Chaque envoi est un tableau JSON. Celoxis peut regrouper plusieurs événements correspondants en une seule requête POST ; votre récepteur doit donc parcourir le tableau plutôt que de supposer un objet unique.

Un événement de tâche modifiée typique ressemble à ceci :

Exemple de charge utile Webhook

JSON

[ { "type": "tasks.modified", "eventId": "<unique-event-id> ", "occurredAt": "<UTC ISO timestamp> ", "acteur": { "valeur": 123, "texte": "Alex Morgan" }, "ressource": { "type": "tâches", "id": 456, "texte": "Préparer la présentation de lancement client", "url": "https://app.celoxis.com/..." }, "modifications": [ { "champ": "nom", "étiquette": "Nom", "précédent": { "valeur": "Brouillon de présentation de lancement", "texte": "Brouillon de présentation de lancement" }, "actuel": { "valeur": "Préparer la présentation de lancement client", "texte": "Préparer la présentation de lancement client" } } ] } ]

Quelques détails qui permettent de gagner du temps lors de la mise en œuvre :

• Les modifications apparaissent lors des événements de mise à jour (*.modified). Les événements d'ajout et de suppression n'incluent pas de comparaison champ par champ.
• La suppression des données conserve le type et l'identifiant de la ressource. Le nom et l'URL sont omis car l'enregistrement a déjà été supprimé.
• L'approbation ou le rejet des dépenses est enregistré sous forme de notes de frais modifiées, et non en tant que type d'événement distinct.
• Utilisez eventId et X-Celoxis-Delivery-Id pour la journalisation et l'idempotence afin qu'une nouvelle tentative ne crée pas un message Slack en double ou une deuxième ligne de facture.

Votre terminal doit répondre rapidement avec un code 200, 201 ou 204. Effectuez le traitement principal après avoir accusé réception de la requête. Si Celoxis ne reçoit pas de code 2xx, la livraison reste en attente et des tentatives sont effectuées à nouveau.

Avant de commencer, vous avez besoin de deux choses : un accès administrateur avec l’ « Accès aux webhooks » et une URL de point de terminaison où Celoxis doit envoyer les notifications. Utilisez HTTPS en production.

1. Ouvrez la page Webhooks. Dans le menu de votre profil, accédez à Administration, puis Intégrations, puis Webhooks. Si aucun webhook n'est encore configuré, la liste sera vide.
2. Cliquez sur + Ajouter. Le formulaire Ajouter un webhook s'ouvre alors.
3. Remplissez le formulaire.
   • Nom : un nom clair, comme « Notifier Slack : Nouvelles tâches », afin que toute personne consultant vos webhooks ultérieurement comprenne leur utilité.
   • URL : votre point de terminaison, saisi avec soin
   • Secret : cliquez sur « Générer un secret ». Celoxis utilise ce secret pour signer chaque notification envoyée. Votre système de réception utilise le même secret pour confirmer l’authenticité de la requête. Les secrets générés commencent par whsec_.
   • Activé : laissez cette option activée pour commencer à recevoir des notifications immédiatement.
   • Événements : choisissez au moins une activité dans la liste ci-dessus.
4. Enregistrer. Votre webhook apparaît désormais sous « Vos URL de webhook ».

À partir de là, vous pouvez modifier à tout moment le nom, l'URL, le secret ou la sélection d'événements, désactiver temporairement un webhook sans le supprimer, ou le supprimer définitivement si vous êtes sûr de ne plus en avoir besoin.

Une limite à prendre en compte : Celoxis autorise jusqu’à cinq webhooks par entreprise. Réfléchissez bien à vos besoins d’intégration avant de les créer un par un. Si plusieurs systèmes en aval doivent réagir aux mêmes événements, configurez un webhook vers un routeur interne ou une plateforme iPaaS et étendez-le à partir de là, plutôt que de réserver un emplacement pour chaque destination.

Si vous mettez à jour l'URL du point de terminaison, les livraisons en attente et ayant échoué sont redirigées vers la nouvelle adresse. Les événements déjà livrés restent inchangés.

Cette section est celle qui aura le plus d'importance pour un directeur technique chargé d'examiner si les webhooks peuvent être exposés en toute sécurité à un point de terminaison externe ; il est donc important de bien la comprendre plutôt que de la survoler.

Chaque requête envoyée par Celoxis inclut trois en-têtes en plus du corps JSON :

Comment la signature est générée

Celoxis joint l'horodatage et le corps brut du message à un point, puis traite ce texte combiné via HMAC-SHA256 en utilisant votre secret :

HMAC-SHA256(secret, « {timestamp}.{rawBody} »)

Le résultat est envoyé sous la forme de la valeur v1= dans X-Celoxis-Signature. Un même secret et un même message produisent toujours la même signature, mais il est impossible de retrouver le secret à partir de cette signature.

Comment le vérifier de votre côté

1. Utilisez le message tel quel. Ne le reformatez pas et ne le reconstruisez pas au préalable ; même une petite modification pourrait compromettre la correspondance.
2. Extrayez l'horodatage et la signature des en-têtes de la requête.
3. Recréez vous-même la signature en utilisant HMAC-SHA256 et votre copie du secret.
4. Comparez les deux. S'ils correspondent, la demande est légitime et vous pouvez l'accepter. Sinon, refusez-la.

Il est recommandé, par mesure de précaution supplémentaire, de rejeter toute requête dont l'horodatage date de plus de quelques minutes (cinq minutes constituent une valeur par défaut raisonnable) afin d'empêcher la réutilisation ultérieure d'un message intercepté. Celoxis ne l'impose pas, mais il s'agit d'une bonne pratique.

Voici un exemple en Node.js de la même vérification :

Vérifier une signature de webhook Celoxis

Node.js

const crypto = require("crypto"); function verifyCeloxisWebhook({ rawBody, timestamp, signatureHeader, secret }) { const expected = crypto .createHmac("sha256", secret) .update(`${timestamp}.${rawBody}`) .digest("hex"); const actual = new URLSearchParams( signatureHeader.replace(/,/g, "&") ).get("v1"); const ageSeconds = Math.abs( Date.now() / 1000 - Number(timestamp) ); if (!actual || ageSeconds > 300) return false; return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(actual) ); }

Gardez ce secret confidentiel. Quiconque le connaît pourrait créer de fausses requêtes d'apparence légitime. Si vous régénérez le secret, mettez-le à jour simultanément côté destinataire, sinon l'ancien deviendra invalide et toutes les requêtes échoueront à la vérification. Les secrets des deux parties doivent toujours correspondre parfaitement.

L'accès aux webhooks est réservé aux administrateurs, et même dans ce cas, un rôle doit disposer de l'autorisation spécifique « Accès aux webhooks » pour pouvoir ouvrir la page correspondante. Sans cette autorisation, les utilisateurs voient un message « Accès refusé ».

Cette fonctionnalité est également soumise à des restrictions d'abonnement. Si les webhooks ne sont pas activés dans votre forfait, le menu ne s'affichera pas. Si vous vous attendiez à le voir et que vous ne le voyez pas, veuillez contacter votre administrateur Celoxis ou le support Celoxis.

Un administrateur accorde l'autorisation depuis le menu principal, puis Admin, puis Paramètres, puis Contrôle d'accès, sous l'onglet Société, en définissant l'accès aux webhooks sur Accorder pour le rôle concerné.

Cela a plus d'importance qu'il n'y paraît. Les webhooks véhiculent des informations confidentielles et une connexion active avec des systèmes externes ; une intégration mal configurée ou négligée peut rapidement entraîner des fuites d'informations ou des perturbations. Les recommandations de Celoxis sont claires à ce sujet : n'accordez pas d'accès aux webhooks aux utilisateurs clients. Il s'agit d'une pratique courante et judicieuse pour toute organisation gérant des données sensibles, qu'elles soient financières ou liées à des projets, et impliquant des parties prenantes internes et externes.

Configurer un webhook n'est pas la fin du travail. Savoir s'il fonctionne correctement est tout aussi important, et Celoxis propose deux vues distinctes pour cela.

La section « Livraisons récentes », accessible depuis la page de détails du webhook, affiche les tentatives en cours et les échecs les plus récents. Elle est conçue pour vous aider à identifier rapidement les problèmes, et non pour constituer un historique exhaustif. Si cette section est vide, cela ne signifie pas qu'aucune livraison n'a été effectuée. Cela signifie simplement qu'aucune livraison n'est actuellement en cours ou n'a échoué. Les livraisons réussies sont enregistrées ailleurs.

L'option « Tout afficher » ouvre l'historique complet des livraisons dans un panneau coulissant, incluant toutes les livraisons marquées comme « Livrées », « En attente » ou « Échec ». En cliquant sur l'icône en forme d'œil dans chaque ligne, vous accédez aux détails complets de la livraison au format JSON, notamment le statut, le nombre de tentatives, le code de réponse HTTP et les données exactes envoyées par Celoxis.

L'état de la livraison se divise en trois catégories :

Pour toute opération en attente ou ayant échoué, commencez par résoudre le problème sous-jacent (URL incorrecte, système de réception hors service, etc.) avant d'utiliser la fonction « Réessayer ». Les envois réussis ne peuvent pas être relancés : c'est le comportement attendu, puisqu'ils ont déjà été effectués.

Cette vue intégrée au produit fait toute la différence entre découvrir soi-même une intégration défaillante et en entendre parler par un client deux semaines plus tard.

La plupart des problèmes liés aux webhooks ont une origine bien précise. Voici les causes les plus fréquentes et comment les résoudre.

Les cas d'utilisation les plus fréquents suivent un schéma récurrent : un changement survient chez Celoxis, et un autre système doit réagir sans intervention humaine.

• Synchronisation CRM : un nouveau projet déclenche automatiquement une transaction ou un enregistrement correspondant, ce qui permet de maintenir l’alignement des ventes et des livraisons sans ressaisie manuelle.
• Notifications d'équipe : la création de tâches ou les changements de statut sont instantanément intégrés à Slack ou Teams, au lieu d'apparaître lors d'une réunion de suivi deux jours plus tard.
• Automatisation de la facturation : le temps enregistré ou une dépense approuvée alimentent directement les flux de travail de facturation ou de paie.
• BI et reporting : les données de projets et de tâches sont intégrées en continu à un entrepôt de données ou à un tableau de bord, au lieu de s’appuyer sur une exportation par lots nocturne qui est toujours un peu obsolète.
• Flux de travail inter-outils : connexion de Celoxis à Jira, Salesforce, ServiceNow ou à un système interne conçu spécifiquement pour le fonctionnement de votre organisation.

Aucune de ces solutions ne nécessite de scripts d'interrogation personnalisés ni de tâches planifiées vérifiant les modifications. Elles requièrent un seul webhook, configuré pour les événements appropriés et pointant vers le point de terminaison adéquat.

Si vous comparez les plateformes, et non pas simplement en adoptant ce que votre outil de gestion de projets propose, quelques questions permettent de distinguer un système de webhooks qui tient la route en production d'un système qui devient un fardeau de maintenance au bout de six mois.

1. Peut-on s'abonner à des événements spécifiques, ou seulement à tous en même temps ? Les flux d'événements larges et non filtrés impliquent de développer sa propre logique de filtrage en aval, ce qui représente du code supplémentaire à maintenir et un risque accru d'erreurs.
2. Chaque requête est-elle signée et la vérification est-elle documentée ? Un webhook sans vérification de signature est une faille de sécurité. Demandez précisément comment fonctionne la signature, et pas seulement si elle existe. Vous avez besoin d'un HMAC, d'un horodatage et d'un identifiant de livraison, et non d'un en-tête partagé que n'importe qui peut copier.
3. Pouvez-vous consulter l'historique des livraisons, ou travaillez-vous à l'aveugle ? Si un webhook échoue silencieusement pendant deux semaines, vous devez pouvoir le savoir, et non pas simplement parce qu'un client signale un problème d'intégration.
4. L'accès à la création et à la gestion des webhooks est-il réellement restreint ? Toute personne capable de créer un webhook peut acheminer des données sensibles du projet vers un système externe. Cette fonctionnalité devrait être soumise à une autorisation spécifique et non accessible par défaut aux administrateurs.
5. Quelle est la limite pratique ? Un plafond strict sur le nombre de webhooks par compte est acceptable, mais il faut en être conscient avant de concevoir cinq intégrations différentes en supposant la possibilité d’en créer une sixième.

Celoxis répond à ces cinq questions dans l'interface d'administration : filtres au niveau de l'événement, signature HMAC-SHA256 avec horodatage et identifiant de livraison, historique de livraison intégré avec visionneuse de charge utile JSON, autorisation d'accès aux webhooks dédiée et une limite publiée de cinq webhooks par entreprise.

Toutes les plateformes de cette catégorie proposent des webhooks sous une forme ou une autre. Leurs différences résident dans la granularité des webhooks, les paramètres de sécurité par défaut et le niveau de visibilité offert une fois le processus lancé. Cette comparaison s'appuie sur la documentation développeur publique de chaque fournisseur, disponible à la date de rédaction.

Plusieurs points méritent d'être soulignés. Celoxis et Wrike prennent en charge le filtrage des événements au niveau du compte ou de l'entreprise sans nécessiter de webhook distinct par tableau, contrairement à ce qu'exige actuellement monday.com. Celoxis est également l'un des rares outils de cette sélection à intégrer la vérification des signatures, le suivi de la distribution et le contrôle des autorisations directement dans l'interface d'administration, sans avoir recours à une API ou à un outil tiers. Asana et monday.com privilégient les outils destinés aux développeurs plutôt qu'une interface intégrée, ce qui convient parfaitement à une équipe d'ingénierie dédiée, mais complexifie la tâche si le bureau de gestion de projet souhaite une visibilité complète sans solliciter l'équipe informatique pour chaque vérification.

Aucune plateforme n'est objectivement « meilleure » ​​sur tous les points. Si votre équipe privilégie les API et bénéficie déjà d'un solide soutien technique, le modèle d'Asana est adapté. Si vous avez besoin d'une visibilité complète et native sans créer de couche de surveillance supplémentaire, la vue de diffusion intégrée de Celoxis est la solution la plus directe.

Les webhooks résolvent un problème spécifique et récurrent : la synchronisation des systèmes sans intervention humaine ni script d'interrogation lent. Les webhooks Celoxis vous offrent un contrôle au niveau de l'événement dès le départ, un processus de vérification HMAC-SHA256 documenté et une vue de suivi de la distribution intégrée au panneau d'administration, et non ajoutée séparément.

La pertinence de cette solution dépend de ce à quoi vous connectez Celoxis, du soutien technique dont vous disposez pour construire et maintenir la partie réceptrice, et du nombre d'intégrations que vous devez exécuter simultanément.

Si vous comparez cette solution à votre configuration actuelle, les étapes de configuration ci-dessus ne prennent que quelques minutes à tester de bout en bout, ce qui est généralement suffisant pour vous indiquer si elle convient.

Configurer votre premier webhook prend une dizaine de minutes si votre point de terminaison est prêt. C'est un excellent moyen de visualiser les données avant de vous engager dans une intégration plus complexe. Si vous préférez voir le processus complet expliqué avec les données de votre propre projet, réservez une démonstration Celoxis ou profitez d'un essai gratuit.