Roasthubs webhook-events

Uitgaande webhooks POST-en JSON naar uw geconfigureerde URL wanneer een overeenkomend event plaatsvindt.

Configureer onder System → Webhooks (één webhook per eventtype).

Hoe dit in Notion te gebruiken

Importeer dit bestand via Notion → Import → Markdown, of plak de inhoud in een nieuwe pagina.

Zet elke groepheading (Lots, Sales, …) om naar een Toggle heading als u een inklapbaar document wilt.

Zet optioneel de samenvatting om naar een Notion-database (één rij per groep).

Samenvatting — wat waar afvuurt

Elke webhook gebruikt dezelfde envelope. Eventspecifieke inhoud zit altijd in data. Gebruik top-level id als idempotency-sleutel.

Lots

Waar: Lot create/update, QC-evaluatie, brandverwerking
Events: lot_create, lot_update, lot_delete, lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail
Typische data: Lotrecord, of target- / QC-resultaat

Productions

Waar: Production planning API
Events: production_create, production_update, production_delete
Typische data: Productierecord

Recipes

Waar: Recipe CRUD + bulk component exchange
Events: recipe_create, recipe_update, recipe_delete, bulk_exchange_recipe_component
Typische data: Receptrecord, of exchange-requestbody

Sales

Waar: Sales / sales-lines API + roast lot processor
Events: sale_create, sale_update, sale_lines_create, sale_lines_update
Typische data: Sale- of sales-line-record

Products

Waar: Products API
Events: product_create, product_update, product_process_stage_create, product_process_stage_update
Typische data: Productvelden, of { product_id, recipe_id, recipe_name }

Contracts & call-offs

Waar: Procurement / contracts APIs + cron / lot weight updates
Events: contracts_create, contracts_update, contracts_call_offs_*, contracts_call_offs_lines_*
Typische data: Contract-, call-off- of line-record

Sites

Waar: Sites API
Events: site_create, site_update
Typische data: Siterecord

Targets

Waar: Lab targets API
Events: target_create, target_update, target_delete
Typische data: Targetrecord

Returns

Waar: Returns API
Events: return_create, return_update, return_add_lot, return_remove_lot
Typische data: Returnrecord, of lot add/remove-payload

Containers

Waar: Containers API + OPC helpers
Events: container_create, container_update, container_delete, container_history_added, plus geseedde varianten
Typische data: { container } of history-entries

Integrations

Waar: Integrations API
Events: integration_create, integration_update, integration_delete
Typische data: Integratierecord

Plant control

Waar: OPC-UA / plant UI (dosing, dump, inventory, scales)
Events: Dump, inventory, dosing skip/cancel/resolve, cell weight correction, scale validation, mode/control
Typische data: Actiespecifieke packets of cell/dump-payloads

Plant nodes

Waar: Plant node update API
Events: plant_node_update
Typische data: Plantknooprecord

System

Waar: Auth / comments
Events: user_log_in, user_log_out, user_comment
Typische data: Commentaartekst, of minimale loginpayload

Opmerking: CRUD-achtige groepen hierboven worden actief geëmit vanuit applicatiecode. Verschillende plant-control- en auth-events (user_log_in / user_log_out, manual_mode_*, tag_update, production_plan_*, …) zijn selecteerbaar in de Webhooks-UI maar vuren mogelijk niet af tot dat pad ze emit.

Delivery

Gedrag	Detail
Method	`POST`
Content-Type	`application/json`
Retries	0–10, exponentiële backoff (`2^attempt × 1000` ms)
Idempotency	Top-level `id`

Gemeenschappelijke envelope

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

Veld	Type	Vereist	Beschrijving
`id`	number	ja	Eventlog-id (idempotency-sleutel)
`type_id`	string	ja	Eventtype-identifier
`user_id`	number	ja	Acterende gebruiker (`0` / `1` = system)
`resource_id`	number	nee	Gerelateerde resource-id
`resource_name`	string	nee	Resource- / tabelnaam
`plant_node_id`	number	nee	Gerelateerde plantknoop
`roasthubs_zone_id`	number	nee	Gerelateerde zone
`data`	object	nee	Eventspecifieke payload

Weggelaten velden kunnen als null verschijnen in opgeslagen events.

Lots

`lot_create`

Aanmaak van een lot.

resource_name: lots (wanneer ingesteld)
resource_id: lot-id
roasthubs_zone_id: lotzone

data — aangemaakt lotrecord:

{
 "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`

Update van een lot (bijv. na branden).

resource_name: lots
resource_id: lot-id

data — bijgewerkt lotrecord.

`lot_delete`

Verwijdering van een lot.

Geseed voor webhooks; bevestig emissie in uw deployment als u erop steunt.

`lot_target_pass` / `lot_target_fail`

Een QC-target op een lot is geëvalueerd.

resource_id: lot-id
roasthubs_zone_id: lotzone

data — de targets-rij (id, parameter_id, lower_bound, upper_bound, recipe_id, …).

Smallere lot_target_pass-variant:

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

`lot_qc_pass` / `lot_qc_fail`

Alle targets voor een lot geëvalueerd; overall QC-resultaat.

resource_id: lot-id
roasthubs_zone_id: lotzone

data — lotrecord inclusief gerelateerde lots_targets.

Productions

`production_create` / `production_update` / `production_delete`

resource_id: productie-id
roasthubs_zone_id: productiezone
plant_node_id: realisation-plantknoop

data — productierecord: 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: recept-id
roasthubs_zone_id: doelzone

data — receptrecord, of bij bulk exchange:

{
 "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`

Verwijdering van een recept.

Geseed voor webhooks; bevestig emissie in uw deployment als u erop steunt.

`bulk_exchange_recipe_component`

resource_name: recipes
resource_id: componentrecept-id die wordt gewisseld
roasthubs_zone_id: typisch 2

data — bulk exchange-requestbody (geselecteerde recepten, exchange coffee id, user id, …).

Sales

`sale_create` / `sale_update`

resource_name: sales
resource_id: sale-id

data — salerecord: id, id_tag, customer_id, customer_name, status, due_date, erp_id, reference, …

`sale_lines_create`

resource_name: sales
resource_id: parent sale-id

data — sales line: id, sale_id, product_id, product_name, qty, weight_ordered, weight_remaining, status, …

`sale_lines_update`

resource_name: sales of sales_lines
resource_id: sale-id of sales line-id (varieert per caller)

data — bijgewerkt sales line-record.

Products

`product_create` / `product_update`

resource_name: products
resource_id: product-id

data — productvelden: id_tag, reference, name, is_producable, mass_smallest_unit, qty_per_product_smallest_unit, price, … (vaak inclusief process stages).

`product_process_stage_create`

resource_id: product-id
resource_name: products (wanneer ingesteld)

data:

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

`product_process_stage_update`

Update van een product process stage.

Geseed voor webhooks; bevestig emissie in uw deployment als u erop steunt.

Contracts & call-offs

`contracts_create` / `contracts_update`

resource_name: contracts
resource_id: contract-id

data — contractrecord of gedeeltelijke update: 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: call-off-id

data — call-off-record: id, id_tag, call_off_number, supplier_id, status, ordered_receiving_date, … — of { "status": "delivered" }.

`contracts_call_offs_lines_create` / `contracts_call_offs_lines_update` / `contracts_call_offs_lines_delete`

resource_name: contracts_call_offs of contracts_call_offs_lines
resource_id: call-off-id (of line-id bij sommige updates)

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

Sites

`site_create` / `site_update`

resource_name: sites
resource_id: site-id

data — siterecord: id, name, address_line1, city, country, time_zone, site_status, unit_system, …

Targets

UI-event-ids: target_create, target_update, target_delete.

Code kan targets_create, targets_update, targets_delete emitten. Match de type_id van een echte webhook-testpayload.

resource_name: targets
resource_id: target-id

data — targetrecord: 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: return-id

data — returnrecord: 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

UI- / seed-ids omvatten container_creation, container_deletion. Geëmitte create/delete-events gebruiken container_create / container_delete. Match de echte type_id.

`container_create` / `container_update` / `container_delete`

resource_name: containers
resource_id: container-id

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: container-id

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"
 }
 ]
}

Andere geseedde containerevents

container_remove_lots
container_added_to_node
container_removed_from_node

Bevestig emissie in uw deployment als u erop steunt.

Integrations

`integration_create` / `integration_update` / `integration_delete`

resource_name: integrations
resource_id: integration-id

data — integratierecord: id, name, basic_auth_username, description, disabled, removed, is_system_integrations, …

Behandel credentials in payloads als gevoelig.

Plant control

`inventory_cell_start`

plant_node_id: broncel-plantknoop
roasthubs_zone_id: zone van broncel

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`

Dezelfde envelope als 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: cel-plantknoop
roasthubs_zone_id: zone

data:

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

actualCellWeight vs correctedCellWeight hangt af van het correctiepad.

`skip_cell_dosing_order` / `resolve_cell_not_found` / `cancel_dosing_order`

roasthubs_zone_id: typisch 2 (roast)

data — client control packet (scalePlantNodeId, recipeId, zone, chosenCells, …).

`dumping_green_lot_fully_finished` / `dumping_green_lot_partially_finished`

roasthubs_zone_id: dumpzone

data:

{ "fullyDumped": true }

`lot_dump_fully_finished` / `lot_dump_partially_finished`

roasthubs_zone_id: bronzone

data:

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

`scale_validation`

resource_name: lots
resource_id: gerelateerde lot-id

data — gerelateerd lotrecord op validatietijd.

Andere geseedde plant-control-events

Event id	Beschrijving
`component_skip`	Een doseerordercomponent overslaan
`coponent_switch`	Een doseerordercomponent wisselen
`dumping_green_start`	Dumping gestart
`manual_control_running`	Asset draait (handmatige bediening)
`manual_control_not_running`	Asset draait niet (handmatige bediening)
`manual_mode_on`	Asset naar handmatige modus geschakeld
`manual_mode_off`	Asset naar automatische modus geschakeld
`production_plan_start`	Productieplan gestart
`production_plan_stop`	Productieplan gestopt
`switching_cell_dosing_order`	Cel wisselen na flow-alarm
`tag_update`	Tag-update
`auto_cell_selection`	Automatische celselectie

System

`user_comment`

resource_name: bijv. contracts
resource_id: gerelateerde resource-id

data:

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

`user_log_in` / `user_log_out`

Gebruikerslogin / -logout.

Geseed voor webhooks; bevestig emissie in uw deployment als u erop steunt.

Plant nodes

`plant_node_update`

resource_name: plant_nodes
resource_id: plantknoop-id

data — plantknoop: id, name, plant_node_type_id, capacity_kg, roasthubs_zone_id, is_blocked_input, is_blocked_output, properties, …

Volledige eventtype-index

Webhook-configureerbare types (enable_webhook: true in seed).

Lots-index

Event id	Beschrijving
`lot_create`	Lot aanmaken
`lot_update`	Lot bijwerken
`lot_delete`	Lot verwijderen

Ook geëmit: lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail.

Productions-index

Event id	Beschrijving
`production_create`	Productie aanmaken
`production_update`	Productie bijwerken
`production_delete`	Productie verwijderen

Recipes-index

Event id	Beschrijving
`recipe_create`	Recept aanmaken
`recipe_update`	Recept bijwerken
`recipe_delete`	Recept verwijderen
`bulk_exchange_recipe_component`	Bulk exchange van een receptcomponent

Sales-index

Event id	Beschrijving
`sale_create`	Sale aanmaken
`sale_update`	Sale bijwerken
`sale_lines_create`	Sale line aanmaken
`sale_lines_update`	Sale line bijwerken

Products-index

Event id	Beschrijving
`product_create`	Product aanmaken
`product_update`	Product bijwerken
`product_process_stage_create`	Product process stage aanmaken
`product_process_stage_update`	Product process stage bijwerken

Contracts & call-offs-index

Event id	Beschrijving
`contracts_create`	Contract aanmaken
`contracts_update`	Contract bijwerken
`contracts_call_offs_create`	Call-off aanmaken
`contracts_call_offs_update`	Call-off bijwerken
`contracts_call_offs_lines_create`	Call-off line aanmaken
`contracts_call_offs_lines_update`	Call-off line bijwerken
`contracts_call_offs_lines_delete`	Call-off line verwijderen

Sites-index

Event id	Beschrijving
`site_create`	Site aanmaken
`site_update`	Site bijwerken

Targets-index

Event id	Beschrijving
`target_create`	Target aanmaken
`target_update`	Target bijwerken
`target_delete`	Target verwijderen

Returns-index

Event id	Beschrijving
`return_create`	Return aanmaken
`return_update`	Return bijwerken
`return_add_lot`	Lot aan return toevoegen
`return_remove_lot`	Lot van return verwijderen

Containers-index

Event id	Beschrijving
`container_creation`	Container aanmaken (UI-id; code kan `container_create` emitten)
`container_update`	Container bijwerken
`container_deletion`	Container verwijderen (UI-id; code kan `container_delete` emitten)
`container_remove_lots`	Loten uit container wissen
`container_added_to_node`	Container gekoppeld aan plantknoop
`container_removed_from_node`	Container ontkoppeld van plantknoop

Ook geëmit: container_history_added.

Integrations-index

Event id	Beschrijving
`integration_create`	Integratie aanmaken
`integration_update`	Integratie bijwerken
`integration_delete`	Integratie verwijderen

Plant control-index

Event id	Beschrijving
`auto_cell_selection`	Automatische celselectie
`cancel_dosing_order`	Volledige doseerorder annuleren
`cell_theoretical_weight_correction`	Theoretische celgewichts correctie
`component_skip`	Doseerordercomponent overslaan
`coponent_switch`	Doseerordercomponent wisselen
`dumping_green_start`	Dumping gestart
`dumping_green_lot_fully_finished`	Groene dump; lot volledig gedumpt
`dumping_green_lot_partially_finished`	Groene dump; lot gedeeltelijk gedumpt
`lot_dump_fully_finished`	Dump gestopt; lot volledig geleegd
`lot_dump_partially_finished`	Dump gestopt; lot gedeeltelijk geleegd
`inventory_cell_start`	Celinventarisatie gestart
`inventory_cell_stop`	Celinventarisatie gestopt
`manual_control_running`	Handmatige bediening draait
`manual_control_not_running`	Handmatige bediening draait niet
`manual_mode_on`	Handmatige modus aan
`manual_mode_off`	Automatische modus aan
`production_plan_start`	Productieplan gestart
`production_plan_stop`	Productieplan gestopt
`resolve_cell_not_found`	Ontbrekende celcomponent oplossen
`scale_validation`	Weegschaalvalidatie
`skip_cell_dosing_order`	Celdoseerorder overslaan
`switching_cell_dosing_order`	Cel wisselen voor doseerorder
`tag_update`	Tag-update

Ook geëmit: plant_node_update.

System-index

Event id	Beschrijving
`user_log_in`	Gebruiker logt in
`user_log_out`	Gebruiker logt uit
`user_comment`	Gebruikerscommentaar

Voorbeeldreceiver

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"
 }
}

Antwoord met 2xx zodat Roasthubs delivery als geslaagd beschouwt. Non-2xx-responses triggeren retries volgens de retry_count van de webhook.

Samenvatting — wat waar afvuurt
Delivery
Gemeenschappelijke envelope
Lots
Productions
- production_create / production_update / production_delete
Recipes
Sales
Products
Contracts & call-offs
Sites
- site_create / site_update
Targets
Returns
Containers
Integrations
- integration_create / integration_update / integration_delete
Plant control
System
- user_comment
- user_log_in / user_log_out
Plant nodes
- plant_node_update
Volledige eventtype-index
Voorbeeldreceiver

Samenvatting — wat waar afvuurt​

Lots​

Productions​

Recipes​

Sales​

Products​

Contracts & call-offs​

Sites​

Targets​

Returns​

Containers​

Integrations​

Plant control​

Plant nodes​

System​

Delivery​

Gemeenschappelijke envelope​

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​

Contracts & 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​

Andere geseedde containerevents​

Integrations​

integration_create / integration_update / integration_delete​

Plant control​

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​

Andere geseedde plant-control-events​

System​

user_comment​

user_log_in / user_log_out​

Plant nodes​

plant_node_update​

Volledige eventtype-index​

Lots-index​

Productions-index​

Recipes-index​

Sales-index​

Products-index​

Contracts & call-offs-index​

Sites-index​

Targets-index​

Returns-index​

Containers-index​

Integrations-index​

Samenvatting — wat waar afvuurt

Lots

Productions

Recipes

Sales

Products

Contracts & call-offs

Sites

Targets

Returns

Containers

Integrations

Plant control

Plant nodes

System

Delivery

Gemeenschappelijke envelope

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`

Contracts & 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`

Andere geseedde containerevents

Integrations

`integration_create` / `integration_update` / `integration_delete`

Plant control

`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`

Andere geseedde plant-control-events

System

`user_comment`

`user_log_in` / `user_log_out`

Plant nodes

`plant_node_update`

Volledige eventtype-index

Lots-index

Productions-index

Recipes-index

Sales-index

Products-index

Contracts & call-offs-index

Sites-index

Targets-index

Returns-index

Containers-index

Integrations-index