Événements webhook Roasthubs

Les webhooks sortants envoient un POST JSON vers l'URL configurée lorsqu'un événement correspondant se produit.

Configurez sous System → Webhooks (un webhook par type d'événement).

Comment utiliser ceci dans Notion

Importez ce fichier via Notion → Import → Markdown, ou collez le contenu dans une nouvelle page.

Transformez chaque titre de groupe (Lots, Sales, …) en titre Toggle si vous voulez un document repliable.

Transformez éventuellement la section résumé en base de données Notion (une ligne par groupe).

Résumé — ce qui se déclenche où

Chaque webhook utilise la même enveloppe. Le contenu spécifique à l'événement est toujours dans data. Utilisez l'id de premier niveau comme clé d'idempotence.

Lots

Où : Création/mise à jour de lot, évaluation QC, traitement torréfaction
Événements : lot_create, lot_update, lot_delete, lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail
Données typiques : Enregistrement de lot, ou résultat cible / QC

Productions

Où : API de planification de production
Événements : production_create, production_update, production_delete
Données typiques : Enregistrement de production

Recipes

Où : CRUD recettes + échange de composants en masse
Événements : recipe_create, recipe_update, recipe_delete, bulk_exchange_recipe_component
Données typiques : Enregistrement de recette, ou corps de requête d'échange

Sales

Où : API ventes / lignes de vente + processeur de lots torréfiés
Événements : sale_create, sale_update, sale_lines_create, sale_lines_update
Données typiques : Enregistrement de vente ou de ligne de vente

Products

Où : API produits
Événements : product_create, product_update, product_process_stage_create, product_process_stage_update
Données typiques : Champs produit, ou { product_id, recipe_id, recipe_name }

Contrats et call-offs

Où : APIs achats / contrats + cron / mises à jour de poids de lot
Événements : contracts_create, contracts_update, contracts_call_offs_*, contracts_call_offs_lines_*
Données typiques : Enregistrement de contrat, call-off ou ligne

Sites

Où : API sites
Événements : site_create, site_update
Données typiques : Enregistrement de site

Targets

Où : API cibles laboratoire
Événements : target_create, target_update, target_delete
Données typiques : Enregistrement de cible

Returns

Où : API retours
Événements : return_create, return_update, return_add_lot, return_remove_lot
Données typiques : Enregistrement de retour, ou charge utile d'ajout/retrait de lot

Containers

Où : API conteneurs + helpers OPC
Événements : container_create, container_update, container_delete, container_history_added, plus variantes seedées
Données typiques : { container } ou entrées d'historique

Integrations

Où : API intégrations
Événements : integration_create, integration_update, integration_delete
Données typiques : Enregistrement d'intégration

Contrôle usine

Où : OPC-UA / UI usine (dosage, dump, inventaire, balances)
Événements : Dump, inventaire, skip/annulation/résolution de dosage, correction de poids de cellule, validation de balance, mode/contrôle
Données typiques : Paquets spécifiques à l'action ou charges utiles cellule/dump

Nœuds d'usine

Où : API de mise à jour des nœuds d'usine
Événements : plant_node_update
Données typiques : Enregistrement de nœud d'usine

System

Où : Auth / commentaires
Événements : user_log_in, user_log_out, user_comment
Données typiques : Texte de commentaire, ou charge utile de connexion minimale

Remarque : Les groupes de type CRUD ci-dessus sont activement émis depuis le code de l'application. Plusieurs événements de contrôle usine et d'auth (user_log_in / user_log_out, manual_mode_*, tag_update, production_plan_*, …) sont sélectionnables dans l'UI Webhooks mais peuvent ne pas se déclencher tant que ce chemin ne les émet pas.

Livraison

Comportement	Détail
Méthode	`POST`
Content-Type	`application/json`
Nouvelles tentatives	0–10, backoff exponentiel (`2^attempt × 1000` ms)
Idempotence	`id` de premier niveau

Enveloppe commune

{
 "id": 12345,
 "type_id": "lot_create",
 "user_id": 1,
 "resource_id": 42,
 "resource_name": "lots",
 "plant_node_id": null,
 "roasthubs_zone_id": 1,
 "data": {}
}

Champ	Type	Requis	Description
`id`	number	oui	Id du journal d'événements (clé d'idempotence)
`type_id`	string	oui	Identifiant du type d'événement
`user_id`	number	oui	Utilisateur agissant (`0` / `1` = système)
`resource_id`	number	non	Id de ressource associée
`resource_name`	string	non	Nom de ressource / table
`plant_node_id`	number	non	Nœud d'usine associé
`roasthubs_zone_id`	number	non	Zone associée
`data`	object	non	Charge utile spécifique à l'événement

Les champs omis peuvent apparaître comme null dans les événements stockés.

Lots

`lot_create`

Création d'un lot.

resource_name : lots (lorsqu'il est défini)
resource_id : id du lot
roasthubs_zone_id : zone du lot

data — enregistrement de lot créé :

{
 "id": 42,
 "id_tag": "L-0042",
 "number": "BATCH-1",
 "recipe_id": 10,
 "roasthubs_zone_id": 1,
 "remaining_weight_kg": 60,
 "actual_weight_kg_input": 60,
 "expected_weight_kg_input": 60,
 "status": "created",
 "erp_id": null,
 "supplier_id": 3,
 "contracts_call_offs_line_id": null,
 "created_at": "2026-09-03T10:00:00.000Z"
}

`lot_update`

Mise à jour d'un lot (par ex. après torréfaction).

resource_name : lots
resource_id : id du lot

data — enregistrement de lot mis à jour.

`lot_delete`

Suppression d'un lot.

Seedé pour les webhooks ; confirmez l'émission dans votre déploiement si vous vous y fiez.

`lot_target_pass` / `lot_target_fail`

Une cible QC sur un lot a été évaluée.

resource_id : id du lot
roasthubs_zone_id : zone du lot

data — la ligne targets (id, parameter_id, lower_bound, upper_bound, recipe_id, …).

Variante plus étroite de lot_target_pass :

{ "status": "pass", "target_id": 7 }

`lot_qc_pass` / `lot_qc_fail`

Toutes les cibles d'un lot évaluées ; résultat QC global.

resource_id : id du lot
roasthubs_zone_id : zone du lot

data — enregistrement de lot incluant les lots_targets associés.

Productions

`production_create` / `production_update` / `production_delete`

resource_id : id de production
roasthubs_zone_id : zone de production
plant_node_id : nœud d'usine de réalisation

data — enregistrement de production : id, name, recipe_id, batch_size_kg, batch_qty, status, type, due_date, product_id, order_line_id, …

Recipes

`recipe_create` / `recipe_update`

resource_name : recipes
resource_id : id de recette
roasthubs_zone_id : zone cible

data — enregistrement de recette, ou lors d'un échange en masse :

{
 "text": "A recipe component id 5 is exchange for 12 and has been updated by bulk exchange",
 "recipe_id": 20,
 "exchangeCoffee": 12,
 "updated_by_user_id": 1
}

`recipe_delete`

Suppression d'une recette.

Seedé pour les webhooks ; confirmez l'émission dans votre déploiement si vous vous y fiez.

`bulk_exchange_recipe_component`

resource_name : recipes
resource_id : id de la recette composant échangée
roasthubs_zone_id : typiquement 2

data — corps de requête d'échange en masse (recettes sélectionnées, id café d'échange, id utilisateur, …).

Sales

`sale_create` / `sale_update`

resource_name : sales
resource_id : id de vente

data — enregistrement de vente : id, id_tag, customer_id, customer_name, status, due_date, erp_id, reference, …

`sale_lines_create`

resource_name : sales
resource_id : id de vente parent

data — ligne de vente : id, sale_id, product_id, product_name, qty, weight_ordered, weight_remaining, status, …

`sale_lines_update`

resource_name : sales ou sales_lines
resource_id : id de vente ou id de ligne de vente (varie selon l'appelant)

data — enregistrement de ligne de vente mis à jour.

Products

`product_create` / `product_update`

resource_name : products
resource_id : id de produit

data — champs produit : id_tag, reference, name, is_producable, mass_smallest_unit, qty_per_product_smallest_unit, price, … (incluant souvent les étapes de process).

`product_process_stage_create`

resource_id : id de produit
resource_name : products (lorsqu'il est défini)

data :

{
 "product_id": 10,
 "recipe_id": 5,
 "recipe_name": "Espresso blend"
}

`product_process_stage_update`

Mise à jour d'une étape de process produit.

Seedé pour les webhooks ; confirmez l'émission dans votre déploiement si vous vous y fiez.

Contrats et call-offs

`contracts_create` / `contracts_update`

resource_name : contracts
resource_id : id de contrat

data — enregistrement de contrat ou mise à jour partielle : id, id_tag, contract_number, recipe_id, price_per_unit, contract_quantity, status, contract_quantity_remaining_actual, supplier_id, …

`contracts_call_offs_create` / `contracts_call_offs_update`

resource_name : contracts_call_offs
resource_id : id de call-off

data — enregistrement de call-off : id, id_tag, call_off_number, supplier_id, status, ordered_receiving_date, … — ou { "status": "delivered" }.

`contracts_call_offs_lines_create` / `contracts_call_offs_lines_update` / `contracts_call_offs_lines_delete`

resource_name : contracts_call_offs ou contracts_call_offs_lines
resource_id : id de call-off (ou id de ligne sur certaines mises à jour)

data — ligne de call-off : id, contract_id, contract_call_off_id, quantity, status, eudr_dds_number, …

Sites

`site_create` / `site_update`

resource_name : sites
resource_id : id de site

data — enregistrement de site : id, name, address_line1, city, country, time_zone, site_status, unit_system, …

Targets

Ids d'événements UI : target_create, target_update, target_delete.

Le code peut émettre targets_create, targets_update, targets_delete. Faites correspondre le type_id d'une charge utile de test webhook réelle.

resource_name : targets
resource_id : id de cible

data — enregistrement de cible : id, parameter_id, lower_bound, upper_bound, recipe_id, plant_node_id, applies_to_all_lots, removed, …

Returns

`return_create` / `return_update`

resource_name : returns
resource_id : id de retour

data — enregistrement de retour : id, id_tag, name, supplier_id, status, note, …

`return_add_lot`

{
 "return_id": 3,
 "lot_id": 42,
 "add_back_to_contract": true
}

`return_remove_lot`

{
 "return_id": 3,
 "lot_id": 42,
 "remove_from_contract": true
}

Containers

Les ids UI / seed incluent container_creation, container_deletion. Les événements create/delete émis utilisent container_create / container_delete. Faites correspondre le type_id réel.

`container_create` / `container_update` / `container_delete`

resource_name : containers
resource_id : id de conteneur

data :

{
 "container": {
 "id": 1,
 "reference": "BIN-01",
 "status": "active",
 "erp_id": null,
 "capacity": 1000,
 "allowed_maximum_usages": null
 }
}

`container_history_added`

resource_name : containers
resource_id : id de conteneur

data :

{
 "containerId": 1,
 "historyAdded": [
 {
 "id": 10,
 "container_id": 1,
 "lot_id": 42,
 "plant_node_id": 5,
 "action": "add",
 "lot_weight": 60.5,
 "created_at": "2026-09-03T10:00:00.000Z"
 }
 ]
}

Autres événements conteneur seedés

container_remove_lots
container_added_to_node
container_removed_from_node

Confirmez l'émission dans votre déploiement si vous vous y fiez.

Integrations

`integration_create` / `integration_update` / `integration_delete`

resource_name : integrations
resource_id : id d'intégration

data — enregistrement d'intégration : id, name, basic_auth_username, description, disabled, removed, is_system_integrations, …

Traitez les identifiants dans les charges utiles comme sensibles.

Contrôle usine

`inventory_cell_start`

plant_node_id : nœud d'usine de la cellule source
roasthubs_zone_id : zone de la cellule source

data :

{
 "cell_start_weight": 120.5,
 "target_cell_plant_node_id": 8,
 "scale_plant_node_id": 12,
 "source_cell_plant_node_id": 7,
 "source_cell_name": "Silo A1",
 "target_cell_name": "Silo B2"
}

`inventory_cell_stop`

Même enveloppe que start.

data :

{
 "cell_start_weight": 120.5,
 "inventorized_weight": 118.2,
 "target_cell_plant_node_id": 8,
 "scale_plant_node_id": 12,
 "source_cell_plant_node_id": 7,
 "source_cell_name": "Silo A1",
 "target_cell_name": "Silo B2"
}

`cell_theoretical_weight_correction`

plant_node_id : nœud d'usine de la cellule
roasthubs_zone_id : zone

data :

{
 "cellId": 3,
 "initialCellWeight": 100,
 "actualCellWeight": 0,
 "correctedCellWeight": 95.2,
 "initialCellLines": [],
 "correctedCellLines": []
}

actualCellWeight vs correctedCellWeight dépend du chemin de correction.

`skip_cell_dosing_order` / `resolve_cell_not_found` / `cancel_dosing_order`

roasthubs_zone_id : typiquement 2 (roast)

data — paquet de contrôle client (scalePlantNodeId, recipeId, zone, chosenCells, …).

`dumping_green_lot_fully_finished` / `dumping_green_lot_partially_finished`

roasthubs_zone_id : zone de dump

data :

{ "fullyDumped": true }

`lot_dump_fully_finished` / `lot_dump_partially_finished`

roasthubs_zone_id : zone source

data :

{
 "sourcePlantNodeId": 7,
 "sourceLotId": 42,
 "resolvedSourceLotId": 42,
 "lotFullyDumped": true,
 "viaRealisationBufferStop": true
}

`scale_validation`

resource_name : lots
resource_id : id de lot associé

data — enregistrement de lot associé au moment de la validation.

Autres événements de contrôle usine seedés

Id d'événement	Description
`component_skip`	Ignorer un composant d'ordre de dosage
`coponent_switch`	Changer un composant d'ordre de dosage
`dumping_green_start`	Dump démarré
`manual_control_running`	Actif en marche (contrôle manuel)
`manual_control_not_running`	Actif arrêté (contrôle manuel)
`manual_mode_on`	Actif basculé en mode manuel
`manual_mode_off`	Actif basculé en mode automatique
`production_plan_start`	Plan de production démarré
`production_plan_stop`	Plan de production arrêté
`switching_cell_dosing_order`	Changer de cellule après alarme de flux
`tag_update`	Mise à jour de tag
`auto_cell_selection`	Sélection automatique de cellule

System

`user_comment`

resource_name : par ex. contracts
resource_id : id de ressource associée

data :

{ "comment": "Human-readable comment text…" }

`user_log_in` / `user_log_out`

Connexion / déconnexion utilisateur.

Seedé pour les webhooks ; confirmez l'émission dans votre déploiement si vous vous y fiez.

Nœuds d'usine

`plant_node_update`

resource_name : plant_nodes
resource_id : id de nœud d'usine

data — nœud d'usine : id, name, plant_node_type_id, capacity_kg, roasthubs_zone_id, is_blocked_input, is_blocked_output, properties, …

Index complet des types d'événements

Types configurables en webhook (enable_webhook: true dans le seed).

Index Lots

Id d'événement	Description
`lot_create`	Créer un lot
`lot_update`	Mettre à jour un lot
`lot_delete`	Supprimer un lot

Également émis : lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail.

Index Productions

Id d'événement	Description
`production_create`	Créer une production
`production_update`	Mettre à jour une production
`production_delete`	Supprimer une production

Index Recipes

Id d'événement	Description
`recipe_create`	Créer une recette
`recipe_update`	Mettre à jour une recette
`recipe_delete`	Supprimer une recette
`bulk_exchange_recipe_component`	Échange en masse d'un composant de recette

Index Sales

Id d'événement	Description
`sale_create`	Créer une vente
`sale_update`	Mettre à jour une vente
`sale_lines_create`	Créer une ligne de vente
`sale_lines_update`	Mettre à jour une ligne de vente

Index Products

Id d'événement	Description
`product_create`	Créer un produit
`product_update`	Mettre à jour un produit
`product_process_stage_create`	Créer une étape de process produit
`product_process_stage_update`	Mettre à jour une étape de process produit

Index Contrats et call-offs

Id d'événement	Description
`contracts_create`	Créer un contrat
`contracts_update`	Mettre à jour un contrat
`contracts_call_offs_create`	Créer un call-off
`contracts_call_offs_update`	Mettre à jour un call-off
`contracts_call_offs_lines_create`	Créer une ligne de call-off
`contracts_call_offs_lines_update`	Mettre à jour une ligne de call-off
`contracts_call_offs_lines_delete`	Supprimer une ligne de call-off

Index Sites

Id d'événement	Description
`site_create`	Créer un site
`site_update`	Mettre à jour un site

Index Targets

Id d'événement	Description
`target_create`	Créer une cible
`target_update`	Mettre à jour une cible
`target_delete`	Supprimer une cible

Index Returns

Id d'événement	Description
`return_create`	Créer un retour
`return_update`	Mettre à jour un retour
`return_add_lot`	Ajouter un lot au retour
`return_remove_lot`	Retirer un lot du retour

Index Containers

Id d'événement	Description
`container_creation`	Créer un conteneur (id UI ; le code peut émettre `container_create`)
`container_update`	Mettre à jour un conteneur
`container_deletion`	Supprimer un conteneur (id UI ; le code peut émettre `container_delete`)
`container_remove_lots`	Vider les lots du conteneur
`container_added_to_node`	Conteneur lié à un nœud d'usine
`container_removed_from_node`	Conteneur détaché d'un nœud d'usine

Également émis : container_history_added.

Index Integrations

Id d'événement	Description
`integration_create`	Créer une intégration
`integration_update`	Mettre à jour une intégration
`integration_delete`	Supprimer une intégration

Index Contrôle usine

Id d'événement	Description
`auto_cell_selection`	Sélection automatique de cellule
`cancel_dosing_order`	Annuler l'ordre de dosage complet
`cell_theoretical_weight_correction`	Correction théorique du poids de cellule
`component_skip`	Ignorer un composant d'ordre de dosage
`coponent_switch`	Changer un composant d'ordre de dosage
`dumping_green_start`	Dump démarré
`dumping_green_lot_fully_finished`	Dump vert ; lot entièrement déchargé
`dumping_green_lot_partially_finished`	Dump vert ; lot partiellement déchargé
`lot_dump_fully_finished`	Dump arrêté ; lot entièrement vidé
`lot_dump_partially_finished`	Dump arrêté ; lot partiellement vidé
`inventory_cell_start`	Inventaire de cellule démarré
`inventory_cell_stop`	Inventaire de cellule arrêté
`manual_control_running`	Contrôle manuel en marche
`manual_control_not_running`	Contrôle manuel arrêté
`manual_mode_on`	Mode manuel activé
`manual_mode_off`	Mode automatique activé
`production_plan_start`	Plan de production démarré
`production_plan_stop`	Plan de production arrêté
`resolve_cell_not_found`	Résoudre un composant de cellule manquant
`scale_validation`	Validation de balance
`skip_cell_dosing_order`	Ignorer l'ordre de dosage de cellule
`switching_cell_dosing_order`	Changer de cellule pour l'ordre de dosage
`tag_update`	Mise à jour de tag

Également émis : plant_node_update.

Index System

Id d'événement	Description
`user_log_in`	Connexion utilisateur
`user_log_out`	Déconnexion utilisateur
`user_comment`	Commentaire utilisateur

Exemple de récepteur

POST /your-endpoint HTTP/1.1
Content-Type: application/json

{
 "id": 9876,
 "type_id": "lot_create",
 "user_id": 4,
 "resource_id": 42,
 "resource_name": "lots",
 "roasthubs_zone_id": 1,
 "data": {
 "id": 42,
 "id_tag": "L-0042",
 "status": "created"
 }
}

Répondez avec 2xx pour que Roasthubs considère la livraison comme réussie. Les réponses non-2xx déclenchent des nouvelles tentatives selon le retry_count du webhook.

Résumé — ce qui se déclenche où
Livraison
Enveloppe commune
Lots
Productions
- production_create / production_update / production_delete
Recipes
Sales
Products
Contrats et call-offs
Sites
- site_create / site_update
Targets
Returns
Containers
Integrations
- integration_create / integration_update / integration_delete
Contrôle usine
System
- user_comment
- user_log_in / user_log_out
Nœuds d'usine
- plant_node_update
Index complet des types d'événements
Exemple de récepteur

Résumé — ce qui se déclenche où​

Lots​

Productions​

Recipes​

Sales​

Products​

Contrats et call-offs​

Sites​

Targets​

Returns​

Containers​

Integrations​

Contrôle usine​

Nœuds d'usine​

System​

Livraison​

Enveloppe commune​

Lots​

lot_create​

lot_update​

lot_delete​

lot_target_pass / lot_target_fail​

lot_qc_pass / lot_qc_fail​

Productions​

production_create / production_update / production_delete​

Recipes​

recipe_create / recipe_update​

recipe_delete​

bulk_exchange_recipe_component​

Sales​

sale_create / sale_update​

sale_lines_create​

sale_lines_update​

Products​

product_create / product_update​

product_process_stage_create​

product_process_stage_update​

Contrats et call-offs​

contracts_create / contracts_update​

contracts_call_offs_create / contracts_call_offs_update​

contracts_call_offs_lines_create / contracts_call_offs_lines_update / contracts_call_offs_lines_delete​

Sites​

site_create / site_update​

Targets​

Returns​

return_create / return_update​

return_add_lot​

return_remove_lot​

Containers​

container_create / container_update / container_delete​

container_history_added​

Autres événements conteneur seedés​

Integrations​

integration_create / integration_update / integration_delete​

Contrôle usine​

inventory_cell_start​

inventory_cell_stop​

cell_theoretical_weight_correction​

skip_cell_dosing_order / resolve_cell_not_found / cancel_dosing_order​

dumping_green_lot_fully_finished / dumping_green_lot_partially_finished​

lot_dump_fully_finished / lot_dump_partially_finished​

scale_validation​

Autres événements de contrôle usine seedés​

System​

user_comment​

user_log_in / user_log_out​

Nœuds d'usine​

plant_node_update​

Index complet des types d'événements​

Index Lots​

Index Productions​

Index Recipes​

Index Sales​

Index Products​

Index Contrats et call-offs​

Index Sites​

Index Targets​

Index Returns​

Index Containers​

Index Integrations​

Résumé — ce qui se déclenche où

Lots

Productions

Recipes

Sales

Products

Contrats et call-offs

Sites

Targets

Returns

Containers

Integrations

Contrôle usine

Nœuds d'usine

System

Livraison

Enveloppe commune

Lots

`lot_create`

`lot_update`

`lot_delete`

`lot_target_pass` / `lot_target_fail`

`lot_qc_pass` / `lot_qc_fail`

Productions

`production_create` / `production_update` / `production_delete`

Recipes

`recipe_create` / `recipe_update`

`recipe_delete`

`bulk_exchange_recipe_component`

Sales

`sale_create` / `sale_update`

`sale_lines_create`

`sale_lines_update`

Products

`product_create` / `product_update`

`product_process_stage_create`

`product_process_stage_update`

Contrats et call-offs

`contracts_create` / `contracts_update`

`contracts_call_offs_create` / `contracts_call_offs_update`

`contracts_call_offs_lines_create` / `contracts_call_offs_lines_update` / `contracts_call_offs_lines_delete`

Sites

`site_create` / `site_update`

Targets

Returns

`return_create` / `return_update`

`return_add_lot`

`return_remove_lot`

Containers

`container_create` / `container_update` / `container_delete`

`container_history_added`

Autres événements conteneur seedés

Integrations

`integration_create` / `integration_update` / `integration_delete`

Contrôle usine

`inventory_cell_start`

`inventory_cell_stop`

`cell_theoretical_weight_correction`

`skip_cell_dosing_order` / `resolve_cell_not_found` / `cancel_dosing_order`

`dumping_green_lot_fully_finished` / `dumping_green_lot_partially_finished`

`lot_dump_fully_finished` / `lot_dump_partially_finished`

`scale_validation`

Autres événements de contrôle usine seedés

System

`user_comment`

`user_log_in` / `user_log_out`

Nœuds d'usine

`plant_node_update`

Index complet des types d'événements

Index Lots

Index Productions

Index Recipes

Index Sales

Index Products

Index Contrats et call-offs

Index Sites

Index Targets

Index Returns

Index Containers

Index Integrations