Webhooks

Webhooks

Les Webhooks permettent à votre Board d’envoyer des requêtes HTTP à des services externes chaque fois que certains événements se produisent pendant la production — une quantité est enregistrée, une tâche est démarrée, une tâche est bloquée, une tâche est terminée, et plus. C’est ainsi que vous connectez votre Board à Slack, Microsoft Teams, un ERP, une plateforme de notification, un script personnalisé ou tout ce qui peut recevoir une requête HTTP.

Les Webhooks vivent dans Paramètres de l’application → Webhooks.

Note : Les Webhooks doivent être activés pour votre compte. Si la page affiche un avis indiquant que les webhooks sont désactivés, contactez le support pour les activer.

---

Table des matières

1. Qu’est-ce qu’un webhook ?
2. Quand utiliser les webhooks
3. Créer un webhook
4. Référence des champs
5. Événements auxquels vous pouvez vous abonner
6. Référence de la charge utile
7. Authentification (clé API)
8. Ciblage de poste de travail
9. Tester un webhook
10. Exemples concrets
11. Journaux et dépannage
12. Notes de sécurité

---

Qu’est-ce qu’un webhook ?

Un webhook est une URL que vous donnez à votre Board. Chaque fois qu’un événement auquel vous vous êtes abonné se produit, le Board envoie une requête HTTP POST à cette URL avec une petite charge utile JSON décrivant ce qui s’est passé.

L’autre extrémité est votre choix — une URL de webhook entrant Slack, un déclencheur « Catch Hook » Zapier, un point de terminaison sur votre propre serveur, une plateforme d’automatisation, tout ce qui peut recevoir HTTP et analyser JSON.

Les webhooks sont unidirectionnels et fire-and-forget — le Board n’attend pas de réponse significative, il enregistre simplement le code de statut pour le diagnostic. Si votre point de terminaison est lent ou temporairement indisponible, le Board ne réessaye pas automatiquement.

---

Quand utiliser les webhooks

Quelques cas d’usage réels :

• Notifications — publier un message dans Slack/Teams chaque fois qu’une tâche est bloquée, qu’une tâche est terminée ou qu’une tâche prioritaire démarre sur un poste de travail spécifique.
• Synchronisation ERP / comptabilité — faire savoir à votre système back-office que les quantités ont été fabriquées afin que l’inventaire et la facturation puissent se mettre à jour.
• Tableaux de bord personnalisés — alimenter un Grafana externe, Looker ou un tableau de bord maison avec des données de production en temps réel.
• Déclencher d’autres automatisations — lancer l’impression d’étiquettes d’expédition, des instructions d’emballage ou des flux de contrôle qualité lorsqu’une tâche atteint un statut terminé.
• Journalisation d’audit / conformité — diffuser chaque changement de quantité ou journal de temps vers une archive externe.

---

Créer un webhook

1. Allez dans Paramètres de l’application → Webhooks.
2. Remplissez le formulaire en haut de la page :
   • Source — quelle source de commande devrait déclencher ce webhook (ou Toutes les sources).
   • URL du webhook — l’URL que votre service externe expose.
   • Clé API (optionnel) — un jeton d’authentification (voir Authentification).
   • Événements — cochez un ou plusieurs événements que vous souhaitez recevoir.
   • Postes de travail (optionnel) — choisissez des postes de travail spécifiques à cibler, ou laissez vide pour déclencher pour tous les postes de travail.
3. Cliquez sur Ajouter (ou Mettre à jour si vous modifiez un webhook existant).

Le nouveau webhook apparaît dans le tableau ci-dessous. Vous pouvez le modifier à tout moment, le supprimer ou envoyer une requête de test manuelle.

---

Référence des champs

Champ	Description
Source	La source de commande à laquelle le webhook s’applique. Choisissez Toutes les sources pour recevoir des événements pour les commandes de n’importe quelle source, ou choisissez une clé de source spécifique (manual, shopify, etc.) pour ne déclencher que lorsque la commande de la tâche provient de cette source.
URL du webhook	L’URL HTTPS complète à laquelle le Board doit POSTer. Maximum 2000 caractères.
Clé API (optionnel)	Si définie, le Board l’envoie sur chaque requête dans deux en-têtes — Authorization: Bearer <key> et X-API-Key: <key>. Utilisez-la si votre point de terminaison nécessite une authentification. Laissez vide pour les points de terminaison publics (par exemple, les webhooks entrants Slack).
Événements	Un ou plusieurs événements qui déclenchent ce webhook. Voir Événements.
Postes de travail (optionnel)	Une liste de postes de travail sur lesquels ce webhook est ciblé. Vide = déclenche pour tous les postes de travail. Voir Ciblage de poste de travail.

---

Événements auxquels vous pouvez vous abonner

Chaque webhook ne se déclenche que pour les événements que vous avez cochés. Vous pouvez en cocher autant que vous le souhaitez.

qty_changed — Quantité modifiée

Se déclenche chaque fois qu’une quantité est enregistrée pour un poste de travail sur n’importe quelle tâche — via le tableau de bord, le Kiosk, l’application mobile ou l’API. La charge utile inclut le poste de travail, le total fabriqué jusqu’à présent pour la tâche, et les champs d’identification concernant la tâche et la commande.

Exemple d’usage : alimenter un système ERP en temps réel avec l’avancement de fabrication.

time_log_saved — Journal de temps enregistré

Se déclenche chaque fois qu’une entrée de journal de suivi du temps est créée — soit manuellement via le bouton « Soumettre » du Kiosk, soit lorsqu’un minuteur est arrêté. La charge utile inclut la durée en minutes, l’employé, le poste de travail, toute note, et la quantité (le cas échéant) qui a été enregistrée en même temps.

Exemple d’usage : enregistrer la productivité dans un système de facturation/paie.

job_blocked — Tâche bloquée

Se déclenche lorsqu’un employé marque une tâche comme bloquée (par exemple, « matériau manquant », « machine en panne »). La charge utile inclut la note de blocage expliquant la raison.

Exemple d’usage : publier une alerte immédiate sur Slack afin qu’un superviseur puisse enquêter.

job_completed — Tâche terminée (tâche entière)

Se déclenche lorsqu’une tâche entière est terminée — c.-à-d. lorsque le statut de la tâche passe au statut d’achèvement configuré (soit changé manuellement, soit automatiquement lorsque chaque poste de travail atteint sa quantité planifiée). La charge utile inclut la durée totale en minutes sur toutes les entrées de suivi du temps de la tâche.

Exemple d’usage : déclencher un flux d’étiquette d’expédition ou de facturation une fois qu’une tâche est entièrement terminée.

task_started — Tâche démarrée à un poste de travail

Se déclenche une fois par poste de travail par tâche, la première fois qu’une activité y est enregistrée. Activité signifie soit la première quantité > 0 enregistrée, soit le premier minuteur de suivi du temps démarré sur ce poste de travail — selon ce qui vient en premier. La charge utile inclut un horodatage ISO started_at.

Exemple d’usage : notifier un superviseur que le travail a commencé sur une étape critique, afin qu’il sache que la production a réellement commencé.

task_completed — Tâche terminée à un poste de travail

Se déclenche une fois par poste de travail par tâche, la première fois que ce poste de travail atteint sa quantité planifiée (ou pour les départements à quantité partagée, le moment où la quantité du département mise en commun atteint le total de la tâche). La charge utile inclut un horodatage ISO completed_at.

Exemple d’usage : déclencher le système aval de l’étape suivante (emballage, QA, expédition) au moment où une étape de production spécifique se termine.

Idempotence pour task_started / task_completed : chacun est enregistré de façon permanente sur la ligne de poste de travail, donc il ne se déclenche que la première fois que la condition est remplie. Enregistrer plus de quantité ou redémarrer un minuteur après le premier déclenchement ne fera pas se déclencher à nouveau ces événements.

---

Référence de la charge utile

Chaque événement envoie un objet JSON via HTTP POST. Certains champs sont communs à tous les événements ; d’autres sont spécifiques au type d’événement. Les champs vides/null sont omis pour garder les charges utiles compactes.

Champs de base (présents pour tous les événements)

{
    "event": "qty_changed",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "order_external_id": "EXT-12345",
    "manufactured_qty": 7,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "external_id": "ORD-7890",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12
}

Champ	Signification
event	La clé de l’événement — l’un des six listés ci-dessus.
job_ref	Le numéro de référence de la tâche sur votre Board.
order_ref	La référence de la commande parente, le cas échéant.
order_external_id	L’ID externe de la commande (par exemple, un ID de commande Shopify).
manufactured_qty	Quantité totale fabriquée pour cette tâche sur tous les postes de travail. (Pour time_log_saved, c’est le total du poste de travail, pas celui de la tâche.)
sku	Le SKU de la tâche.
name	Le nom de la tâche.
external_id	L’ID externe de la tâche (par exemple, l’identifiant du système amont).
department	Département du poste de travail impliqué, si un poste de travail est en contexte.
workstation	Nom du poste de travail impliqué.
workstation_id	ID numérique du poste de travail impliqué.

Les champs department, workstation et workstation_id sont présents chaque fois que l’événement concerne un poste de travail spécifique (donc tous les événements sauf job_completed, qui est au niveau de la tâche entière).

Extras par événement

Événement	Champs supplémentaires
qty_changed	—
time_log_saved	mode ("manual" ou "work_stopped"), log_qty, log_note, duration_minutes, employee (objet avec id, name, surname)
job_blocked	block_note
job_completed	status (nom du statut d’achèvement), total_duration_minutes
task_started	started_at (horodatage ISO 8601)
task_completed	completed_at (horodatage ISO 8601)

Exemple : charge utile task_started

{
    "event": "task_started",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "manufactured_qty": 0,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "started_at": "2026-05-27T08:14:32+00:00"
}

Exemple : charge utile time_log_saved

{
    "event": "time_log_saved",
    "job_ref": "PB-0042",
    "manufactured_qty": 5,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "mode": "work_stopped",
    "log_qty": 2,
    "log_note": "Two units finished, third in progress",
    "duration_minutes": 47,
    "employee": { "id": 8, "name": "Jan", "surname": "Kowalski" }
}

---

Authentification (clé API)

Si votre point de terminaison nécessite une authentification, remplissez le champ Clé API. Le Board l’envoie sur chaque requête dans deux en-têtes :

Authorization: Bearer <your-api-key>
X-API-Key: <your-api-key>

La plupart des points de terminaison acceptent l’une ou l’autre forme, donc peu importe laquelle vous vérifiez du côté récepteur.

Laissez Clé API vide pour les points de terminaison publics comme les webhooks entrants Slack — ils n’attendent aucun en-tête d’auth.

---

Ciblage de poste de travail

Par défaut, un webhook se déclenche pour chaque poste de travail. Le champ optionnel Postes de travail vous permet de restreindre cela.

Liste vide (par défaut)

Le webhook se déclenche pour tous les postes de travail. C’est le comportement original — les webhooks existants créés avant cette fonctionnalité ne sont pas affectés.

Postes de travail spécifiques

Le webhook ne se déclenche que lorsque le poste de travail de l’événement est dans la liste. Utile lorsque :

• Vous voulez qu’un canal Slack reçoive des alertes uniquement pour les postes de travail de l’équipe peinture.
• Vous voulez une intégration ERP qui ne se soucie que des postes de travail d’assemblage final.
• Des équipes différentes devraient recevoir des notifications différentes.

Comportement avec les événements non-poste de travail

L’événement job_completed est déclenché au niveau de la tâche entière (pas de poste de travail spécifique). Un webhook avec un ou plusieurs postes de travail sélectionnés ne se déclenchera pas pour job_completed — par conception. Si vous voulez qu’un webhook reçoive job_completed, laissez la liste de postes de travail vide (ou créez un deuxième webhook juste pour cet événement).

Combiné avec Source

Le filtre de poste de travail est appliqué par-dessus le filtre de source. Un webhook avec source=shopify et postes de travail [A, B] ne se déclenche que lorsque l’événement correspond aux deux — un événement de tâche de source Shopify se produisant sur le poste de travail A ou B.

---

Tester un webhook

Le tableau des webhooks a une icône avion en papier (✈) à côté de chaque ligne — cliquez dessus pour ouvrir la boîte de dialogue de test.

1. Choisissez un événement parmi les événements souscrits de votre webhook.
2. Un exemple de charge utile est rendu en JSON. Modifiez-le librement — changez n’importe quel champ pour simuler un scénario réel.
3. Cliquez sur Envoyer le test. La boîte de dialogue bascule sur un panneau de résultat affichant :
   • Le code de statut HTTP retourné par votre point de terminaison
   • Le temps pris (en millisecondes)
   • Le corps de la réponse (tronqué à 2 Ko)
   • Toute erreur de connexion
4. Cliquez sur Retour à l’édition pour ajuster la charge utile et réessayer.

C’est le moyen le plus rapide de vérifier que votre point de terminaison est accessible, analyse correctement la charge utile et répond avec un statut 2xx.

---

Exemples concrets

1. Alerte Slack lorsqu’une tâche est bloquée

• Source : Toutes les sources
• URL : une URL de webhook entrant Slack
• Clé API : vide
• Événements : job_blocked uniquement
• Postes de travail : vide

Dans Slack, la charge utile arrive en JSON ; vous pouvez la formater joliment avec un relais (par exemple, un Cloudflare Worker qui transforme block_note + workstation en message Slack). Ou utilisez un service comme Zapier entre les deux pour faire le formatage.

2. Envoyer un e-mail à un superviseur lorsque l’atelier de peinture termine une tâche

• Source : Toutes les sources
• URL : une URL « Catch Hook » Zapier connectée à une étape Gmail « Envoyer un e-mail »
• Événements : task_completed
• Postes de travail : cochez tous les postes de travail de l’atelier de peinture

Le webhook se déclenche au moment où la partie atelier de peinture de toute tâche est faite. Zapier formate l’e-mail à partir des champs de la charge utile.

3. Pousser les quantités fabriquées vers un ERP

• Source : une source externe spécifique (par exemple, shopify)
• URL : le point de terminaison entrant de votre ERP
• Clé API : le jeton API de l’ERP
• Événements : qty_changed, job_completed
• Postes de travail : vide (vous les voulez tous)

L’ERP reçoit une charge utile après chaque changement de quantité plus un avis final de tâche entière lorsque la tâche est entièrement terminée.

4. Notifications différentes par département

Créez trois webhooks séparés, chacun ciblé sur les postes de travail de son propre département :

• « Assembly Slack » → task_started, task_completed, job_blocked, postes de travail = postes d’assemblage uniquement
• « Paint Slack » → mêmes événements, postes de travail = postes d’atelier de peinture uniquement
• « Packing Slack » → mêmes événements, postes de travail = postes d’emballage uniquement

Chaque équipe ne voit que les alertes qui la concernent.

---

Journaux et dépannage

Chaque requête webhook — événements réels et tests manuels — est ajoutée à un journal par tenant sur le serveur à :

storage/logs/webhooks/webhook_tennent_id_<tenant_id>.log

Chaque ligne est un objet JSON avec l’horodatage, l’événement, l’URL, le statut HTTP, la durée, la charge utile, le corps de la réponse et toute erreur. C’est le premier endroit où chercher lorsqu’un webhook semble ne pas livrer.

Problèmes courants

• Le point de terminaison retourne 4xx / 5xx — vérifiez le corps de la réponse dans le journal. Le Board n’arrête d’envoyer sur le prochain événement que si l’URL est supprimée ; il ne réessaie pas automatiquement l’événement actuel.
• Aucune ligne de journal pour un événement — votre webhook ne correspond pas. Vérifiez les filtres source, événements et postes de travail. La boîte de dialogue Test contourne ces filtres et est le moyen le plus rapide de confirmer que l’URL fonctionne.
• Point de terminaison lent — le délai d’expiration de requête du Board est de 10 secondes. Si votre point de terminaison prend plus de temps, la connexion est interrompue et une erreur est enregistrée.
• Erreurs HTTPS — assurez-vous que votre point de terminaison a un certificat valide. Le Board n’autorise pas les certificats auto-signés.
• Indicateur tenant désactivé — la page affiche un avis désactivé si les webhooks sont désactivés pour votre compte. Contactez le support.

---

Notes de sécurité

• L’URL elle-même est le justificatif lorsqu’aucune clé API n’est définie. Toute personne qui connaît l’URL d’un webhook non authentifié (par exemple, un webhook entrant Slack) peut y poster. Traitez les URL non authentifiées comme des secrets et ne les partagez pas publiquement.
• Utilisez le champ Clé API chaque fois que votre point de terminaison prend en charge l’auth. C’est une mise à niveau gratuite en sécurité — le Board l’envoie avec chaque requête.
• HTTPS est requis pour tout point de terminaison qui gère des données de production réelles. Le champ URL de webhook accepte aussi http://, mais utilisez-le uniquement pour le développement local.
• Les charges utiles incluent des informations identifiables sur la commande/le client. Assurez-vous que le service récepteur est approuvé pour gérer ces données — en particulier pour les sources externes, les plateformes d’automatisation tierces et tout service qui stocke ou enregistre les charges utiles.
• Les webhooks sont par tenant. Les événements des données d’un tenant ne peuvent jamais atteindre les webhooks d’un autre tenant.