Roasthubs webhook events

Outbound webhooks POST JSON to your configured URL when a matching event occurs.

Configure under System → Webhooks (one webhook per event type).

How to use this in Notion

Import this file via Notion → Import → Markdown, or paste the content into a new page.

Turn each group heading (Lots, Sales, …) into a Toggle heading if you want a collapsible doc.

Optionally turn the summary section into a Notion database (one row per group).

Summary — what fires where

Every webhook uses the same envelope. Event-specific content is always in data. Use top-level id as the idempotency key.

Lots

Where: Lot create/update, QC evaluation, roast processing
Events: lot_create, lot_update, lot_delete, lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail
Typical data: Lot record, or target / QC result

Productions

Where: Production planning API
Events: production_create, production_update, production_delete
Typical data: Production record

Recipes

Where: Recipe CRUD + bulk component exchange
Events: recipe_create, recipe_update, recipe_delete, bulk_exchange_recipe_component
Typical data: Recipe record, or exchange request body

Sales

Where: Sales / sales-lines API + roast lot processor
Events: sale_create, sale_update, sale_lines_create, sale_lines_update
Typical data: Sale or sales-line record

Products

Where: Products API
Events: product_create, product_update, product_process_stage_create, product_process_stage_update
Typical data: Product fields, or { product_id, recipe_id, recipe_name }

Contracts & call-offs

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

Sites

Where: Sites API
Events: site_create, site_update
Typical data: Site record

Targets

Where: Lab targets API
Events: target_create, target_update, target_delete
Typical data: Target record

Returns

Where: Returns API
Events: return_create, return_update, return_add_lot, return_remove_lot
Typical data: Return record, or lot add/remove payload

Containers

Where: Containers API + OPC helpers
Events: container_create, container_update, container_delete, container_history_added, plus seeded variants
Typical data: { container } or history entries

Integrations

Where: Integrations API
Events: integration_create, integration_update, integration_delete
Typical data: Integration record

Plant control

Where: OPC-UA / plant UI (dosing, dump, inventory, scales)
Events: Dump, inventory, dosing skip/cancel/resolve, cell weight correction, scale validation, mode/control
Typical data: Action-specific packets or cell/dump payloads

Plant nodes

Where: Plant node update API
Events: plant_node_update
Typical data: Plant node record

System

Where: Auth / comments
Events: user_log_in, user_log_out, user_comment
Typical data: Comment text, or minimal login payload

Note: CRUD-style groups above are actively emitted from application code. Several plant-control and auth events (user_log_in / user_log_out, manual_mode_*, tag_update, production_plan_*, …) are selectable in the Webhooks UI but may not fire until that path emits them.

Delivery

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

Common 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": {}
}

Field	Type	Required	Description
`id`	number	yes	Event log id (idempotency key)
`type_id`	string	yes	Event type identifier
`user_id`	number	yes	Acting user (`0` / `1` = system)
`resource_id`	number	no	Related resource id
`resource_name`	string	no	Resource / table name
`plant_node_id`	number	no	Related plant node
`roasthubs_zone_id`	number	no	Related zone
`data`	object	no	Event-specific payload

Omitted fields may appear as null in stored events.

Lots

`lot_create`

Creation of a lot.

resource_name: lots (when set)
resource_id: lot id
roasthubs_zone_id: lot zone

data — created lot record:

{
 "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 of a lot (e.g. after roasting).

resource_name: lots
resource_id: lot id

data — updated lot record.

`lot_delete`

Deletion of a lot.

Seeded for webhooks; confirm emission in your deployment if you rely on it.

`lot_target_pass` / `lot_target_fail`

A QC target on a lot was evaluated.

resource_id: lot id
roasthubs_zone_id: lot zone

data — the targets row (id, parameter_id, lower_bound, upper_bound, recipe_id, …).

Narrower lot_target_pass variant:

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

`lot_qc_pass` / `lot_qc_fail`

All targets for a lot evaluated; overall QC result.

resource_id: lot id
roasthubs_zone_id: lot zone

data — lot record including related lots_targets.

Productions

`production_create` / `production_update` / `production_delete`

resource_id: production id
roasthubs_zone_id: production zone
plant_node_id: realisation plant node

data — production record: 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: recipe id
roasthubs_zone_id: target zone

data — recipe record, or on 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`

Deletion of a recipe.

Seeded for webhooks; confirm emission in your deployment if you rely on it.

`bulk_exchange_recipe_component`

resource_name: recipes
resource_id: component recipe id being exchanged
roasthubs_zone_id: typically 2

data — bulk exchange request body (selected recipes, exchange coffee id, user id, …).

Sales

`sale_create` / `sale_update`

resource_name: sales
resource_id: sale id

data — sale record: 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 or sales_lines
resource_id: sale id or sales line id (varies by caller)

data — updated sales line record.

Products

`product_create` / `product_update`

resource_name: products
resource_id: product id

data — product fields: id_tag, reference, name, is_producable, mass_smallest_unit, qty_per_product_smallest_unit, price, … (often including process stages).

`product_process_stage_create`

resource_id: product id
resource_name: products (when set)

data:

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

`product_process_stage_update`

Update of a product process stage.

Seeded for webhooks; confirm emission in your deployment if you rely on it.

Contracts & call-offs

`contracts_create` / `contracts_update`

resource_name: contracts
resource_id: contract id

data — contract record or partial 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, … — or { "status": "delivered" }.

`contracts_call_offs_lines_create` / `contracts_call_offs_lines_update` / `contracts_call_offs_lines_delete`

resource_name: contracts_call_offs or contracts_call_offs_lines
resource_id: call-off id (or line id on some 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 — site record: id, name, address_line1, city, country, time_zone, site_status, unit_system, …

Targets

UI event ids: target_create, target_update, target_delete.

Code may emit targets_create, targets_update, targets_delete. Match the type_id from a real webhook test payload.

resource_name: targets
resource_id: target id

data — target record: 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 — return record: 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 include container_creation, container_deletion. Emitted create/delete events use container_create / container_delete. Match the real 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"
 }
 ]
}

Other seeded container events

container_remove_lots
container_added_to_node
container_removed_from_node

Confirm emission in your deployment if you rely on them.

Integrations

`integration_create` / `integration_update` / `integration_delete`

resource_name: integrations
resource_id: integration id

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

Treat credentials in payloads as sensitive.

Plant control

`inventory_cell_start`

plant_node_id: source cell plant node
roasthubs_zone_id: zone of source cell

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`

Same envelope as 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: cell plant node
roasthubs_zone_id: zone

data:

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

actualCellWeight vs correctedCellWeight depends on the correction path.

`skip_cell_dosing_order` / `resolve_cell_not_found` / `cancel_dosing_order`

roasthubs_zone_id: typically 2 (roast)

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

`dumping_green_lot_fully_finished` / `dumping_green_lot_partially_finished`

roasthubs_zone_id: dump zone

data:

{ "fullyDumped": true }

`lot_dump_fully_finished` / `lot_dump_partially_finished`

roasthubs_zone_id: source zone

data:

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

`scale_validation`

resource_name: lots
resource_id: related lot id

data — related lot record at validation time.

Other seeded plant-control events

Event id	Description
`component_skip`	Skip a dosing-order component
`coponent_switch`	Switch a dosing-order component
`dumping_green_start`	Dumping started
`manual_control_running`	Asset running (manual control)
`manual_control_not_running`	Asset not running (manual control)
`manual_mode_on`	Asset switched to manual mode
`manual_mode_off`	Asset switched to automatic mode
`production_plan_start`	Production plan started
`production_plan_stop`	Production plan stopped
`switching_cell_dosing_order`	Switch cell after flow alarm
`tag_update`	Tag update
`auto_cell_selection`	Automatic cell selection

System

`user_comment`

resource_name: e.g. contracts
resource_id: related resource id

data:

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

`user_log_in` / `user_log_out`

User login / logout.

Seeded for webhooks; confirm emission in your deployment if you rely on them.

Plant nodes

`plant_node_update`

resource_name: plant_nodes
resource_id: plant node id

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

Full event type index

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

Lots index

Event id	Description
`lot_create`	Create lot
`lot_update`	Update lot
`lot_delete`	Delete lot

Also emitted: lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail.

Productions index

Event id	Description
`production_create`	Create production
`production_update`	Update production
`production_delete`	Delete production

Recipes index

Event id	Description
`recipe_create`	Create recipe
`recipe_update`	Update recipe
`recipe_delete`	Delete recipe
`bulk_exchange_recipe_component`	Bulk exchange of a recipe component

Sales index

Event id	Description
`sale_create`	Create sale
`sale_update`	Update sale
`sale_lines_create`	Create sale line
`sale_lines_update`	Update sale line

Products index

Event id	Description
`product_create`	Create product
`product_update`	Update product
`product_process_stage_create`	Create product process stage
`product_process_stage_update`	Update product process stage

Contracts & call-offs index

Event id	Description
`contracts_create`	Create contract
`contracts_update`	Update contract
`contracts_call_offs_create`	Create call-off
`contracts_call_offs_update`	Update call-off
`contracts_call_offs_lines_create`	Create call-off line
`contracts_call_offs_lines_update`	Update call-off line
`contracts_call_offs_lines_delete`	Delete call-off line

Sites index

Event id	Description
`site_create`	Create site
`site_update`	Update site

Targets index

Event id	Description
`target_create`	Create target
`target_update`	Update target
`target_delete`	Delete target

Returns index

Event id	Description
`return_create`	Create return
`return_update`	Update return
`return_add_lot`	Add lot to return
`return_remove_lot`	Remove lot from return

Containers index

Event id	Description
`container_creation`	Create container (UI id; code may emit `container_create`)
`container_update`	Update container
`container_deletion`	Delete container (UI id; code may emit `container_delete`)
`container_remove_lots`	Clear lots from container
`container_added_to_node`	Container linked to plant node
`container_removed_from_node`	Container unlinked from plant node

Also emitted: container_history_added.

Integrations index

Event id	Description
`integration_create`	Create integration
`integration_update`	Update integration
`integration_delete`	Delete integration

Plant control index

Event id	Description
`auto_cell_selection`	Automatic cell selection
`cancel_dosing_order`	Cancel full dosing order
`cell_theoretical_weight_correction`	Theoretical cell weight correction
`component_skip`	Skip dosing-order component
`coponent_switch`	Switch dosing-order component
`dumping_green_start`	Dumping started
`dumping_green_lot_fully_finished`	Green dump; lot fully dumped
`dumping_green_lot_partially_finished`	Green dump; lot partially dumped
`lot_dump_fully_finished`	Dump stopped; lot fully emptied
`lot_dump_partially_finished`	Dump stopped; lot partially emptied
`inventory_cell_start`	Cell inventorization started
`inventory_cell_stop`	Cell inventorization stopped
`manual_control_running`	Manual control running
`manual_control_not_running`	Manual control not running
`manual_mode_on`	Manual mode on
`manual_mode_off`	Automatic mode on
`production_plan_start`	Production plan started
`production_plan_stop`	Production plan stopped
`resolve_cell_not_found`	Resolve missing cell component
`scale_validation`	Weighing scale validation
`skip_cell_dosing_order`	Skip cell dosing order
`switching_cell_dosing_order`	Switch cell for dosing order
`tag_update`	Tag update

Also emitted: plant_node_update.

System index

Event id	Description
`user_log_in`	User logs in
`user_log_out`	User logs out
`user_comment`	User comment

Example receiver

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

Respond with 2xx so Roasthubs treats delivery as successful. Non-2xx responses trigger retries per the webhook’s retry_count.

Summary — what fires where
Delivery
Common 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
Full event type index
Example receiver

Summary — what fires where​

Lots​

Productions​

Recipes​

Sales​

Products​

Contracts & call-offs​

Sites​

Targets​

Returns​

Containers​

Integrations​

Plant control​

Plant nodes​

System​

Delivery​

Common 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​

Other seeded container events​

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​

Other seeded plant-control events​

System​

user_comment​

user_log_in / user_log_out​

Plant nodes​

plant_node_update​

Full event type 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​

Summary — what fires where

Lots

Productions

Recipes

Sales

Products

Contracts & call-offs

Sites

Targets

Returns

Containers

Integrations

Plant control

Plant nodes

System

Delivery

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

Other seeded container events

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`

Other seeded plant-control events

System

`user_comment`

`user_log_in` / `user_log_out`

Plant nodes

`plant_node_update`

Full event type 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