Roasthubs webhook събития

Изходящите уебхукове изпращат POST с JSON към конфигурирания ви URL, когато настъпи съответстващо събитие.

Конфигурирайте под System → Webhooks (един уебхук на тип събитие).

Как да използвате това в Notion

Импортирайте този файл чрез Notion → Import → Markdown или поставете съдържанието в нова страница.

Превърнете всеки заглавен раздел на група (Lots, Sales, …) в Toggle heading, ако искате сгъваем документ.

По желание превърнете раздела със обобщение в Notion база данни (един ред на група).

Обобщение — какво се задейства къде

Всеки уебхук използва една и съща обвивка. Специфичното за събитието съдържание винаги е в data. Използвайте id на най-горно ниво като ключ за идемпотентност.

Lots

Къде: Създаване/обновяване на партида, QC оценка, обработка при изпичане
Събития: lot_create, lot_update, lot_delete, lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail
Типични данни: Запис на партида или резултат от target / QC

Productions

Къде: API за планиране на производството
Събития: production_create, production_update, production_delete
Типични данни: Запис на продукция

Recipes

Къде: CRUD на рецепти + масова смяна на компоненти
Събития: recipe_create, recipe_update, recipe_delete, bulk_exchange_recipe_component
Типични данни: Запис на рецепта или тяло на заявка за смяна

Sales

Къде: API за продажби / sales-lines + процесор за партиди за изпичане
Събития: sale_create, sale_update, sale_lines_create, sale_lines_update
Типични данни: Запис на продажба или ред на продажба

Products

Къде: API за продукти
Събития: product_create, product_update, product_process_stage_create, product_process_stage_update
Типични данни: Полета на продукта или { product_id, recipe_id, recipe_name }

Contracts & call-offs

Къде: API за доставки / договори + cron / обновявания на тегло на партида
Събития: contracts_create, contracts_update, contracts_call_offs_*, contracts_call_offs_lines_*
Типични данни: Запис на договор, повикване или ред

Sites

Къде: API за сайтове
Събития: site_create, site_update
Типични данни: Запис на сайт

Targets

Къде: API за лабораторни цели
Събития: target_create, target_update, target_delete
Типични данни: Запис на цел

Returns

Къде: API за връщания
Събития: return_create, return_update, return_add_lot, return_remove_lot
Типични данни: Запис на връщане или payload за добавяне/премахване на партида

Containers

Къде: API за контейнери + OPC помощници
Събития: container_create, container_update, container_delete, container_history_added, плюс seeded варианти
Типични данни: { container } или записи в историята

Integrations

Къде: API за интеграции
Събития: integration_create, integration_update, integration_delete
Типични данни: Запис на интеграция

Plant control

Къде: OPC-UA / UI на завода (дозиране, dump, инвентар, везни)
Събития: Dump, inventory, dosing skip/cancel/resolve, корекция на тегло на клетка, валидация на везна, mode/control
Типични данни: Пакети, специфични за действието, или payload-и за клетка/dump

Plant nodes

Къде: API за обновяване на възли на завода
Събития: plant_node_update
Типични данни: Запис на възел на завода

System

Къде: Auth / коментари
Събития: user_log_in, user_log_out, user_comment
Типични данни: Текст на коментар или минимален payload за вход

Забележка: CRUD-групите по-горе се излъчват активно от кода на приложението. Някои събития за plant-control и auth (user_log_in / user_log_out, manual_mode_*, tag_update, production_plan_*, …) са избираеми в UI на Webhooks, но може да не се задействат, докато съответният път не ги излъчи.

Доставка

Поведение	Детайл
Method	`POST`
Content-Type	`application/json`
Retries	0–10, експоненциален backoff (`2^attempt × 1000` ms)
Idempotency	`id` на най-горно ниво

Обща обвивка

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

Поле	Тип	Задължително	Описание
`id`	number	да	Id на дневника на събитието (ключ за идемпотентност)
`type_id`	string	да	Идентификатор на типа събитие
`user_id`	number	да	Действащ потребител (`0` / `1` = система)
`resource_id`	number	не	Id на свързания ресурс
`resource_name`	string	не	Име на ресурс / таблица
`plant_node_id`	number	не	Свързан възел на завода
`roasthubs_zone_id`	number	не	Свързана зона
`data`	object	не	Payload, специфичен за събитието

Пропуснатите полета могат да се появят като null в съхранените събития.

Lots

`lot_create`

Създаване на партида.

resource_name: lots (когато е зададено)
resource_id: id на партидата
roasthubs_zone_id: зона на партидата

data — създаден запис на партида:

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

Обновяване на партида (напр. след изпичане).

resource_name: lots
resource_id: id на партидата

data — обновен запис на партида.

`lot_delete`

Изтриване на партида.

Seeded за уебхукове; потвърдете излъчването във вашето внедряване, ако разчитате на него.

`lot_target_pass` / `lot_target_fail`

QC цел върху партида е оценена.

resource_id: id на партидата
roasthubs_zone_id: зона на партидата

data — редът от targets (id, parameter_id, lower_bound, upper_bound, recipe_id, …).

По-тесен вариант на lot_target_pass:

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

`lot_qc_pass` / `lot_qc_fail`

Всички цели за партида са оценени; общ QC резултат.

resource_id: id на партидата
roasthubs_zone_id: зона на партидата

data — запис на партида, включително свързаните lots_targets.

Productions

`production_create` / `production_update` / `production_delete`

resource_id: id на продукцията
roasthubs_zone_id: зона на продукцията
plant_node_id: възел на завода за realisation

data — запис на продукция: 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 на рецептата
roasthubs_zone_id: целева зона

data — запис на рецепта или при масова смяна:

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

Изтриване на рецепта.

Seeded за уебхукове; потвърдете излъчването във вашето внедряване, ако разчитате на него.

`bulk_exchange_recipe_component`

resource_name: recipes
resource_id: id на компонентната рецепта, която се сменя
roasthubs_zone_id: обикновено 2

data — тяло на заявката за масова смяна (избрани рецепти, id на exchange coffee, user id, …).

Sales

`sale_create` / `sale_update`

resource_name: sales
resource_id: id на продажбата

data — запис на продажба: id, id_tag, customer_id, customer_name, status, due_date, erp_id, reference, …

`sale_lines_create`

resource_name: sales
resource_id: id на родителската продажба

data — ред на продажба: id, sale_id, product_id, product_name, qty, weight_ordered, weight_remaining, status, …

`sale_lines_update`

resource_name: sales или sales_lines
resource_id: id на продажба или на ред (варира според извикващия)

data — обновен запис на ред на продажба.

Products

`product_create` / `product_update`

resource_name: products
resource_id: id на продукта

data — полета на продукта: id_tag, reference, name, is_producable, mass_smallest_unit, qty_per_product_smallest_unit, price, … (често включително process stages).

`product_process_stage_create`

resource_id: id на продукта
resource_name: products (когато е зададено)

data:

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

`product_process_stage_update`

Обновяване на етап от процеса на продукт.

Seeded за уебхукове; потвърдете излъчването във вашето внедряване, ако разчитате на него.

Contracts & call-offs

`contracts_create` / `contracts_update`

resource_name: contracts
resource_id: id на договора

data — запис на договор или частично обновяване: 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 на повикването

data — запис на повикване: id, id_tag, call_off_number, supplier_id, status, ordered_receiving_date, … — или { "status": "delivered" }.

`contracts_call_offs_lines_create` / `contracts_call_offs_lines_update` / `contracts_call_offs_lines_delete`

resource_name: contracts_call_offs или contracts_call_offs_lines
resource_id: id на повикването (или id на ред при някои обновявания)

data — ред на повикване: id, contract_id, contract_call_off_id, quantity, status, eudr_dds_number, …

Sites

`site_create` / `site_update`

resource_name: sites
resource_id: id на сайта

data — запис на сайт: id, name, address_line1, city, country, time_zone, site_status, unit_system, …

Targets

UI id на събития: target_create, target_update, target_delete.

Кодът може да излъчва targets_create, targets_update, targets_delete. Съпоставете type_id от реален тестов payload на уебхук.

resource_name: targets
resource_id: id на целта

data — запис на цел: 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 на връщането

data — запис на връщане: 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 id включват container_creation, container_deletion. Излъчваните събития за създаване/изтриване използват container_create / container_delete. Съпоставете реалния type_id.

`container_create` / `container_update` / `container_delete`

resource_name: containers
resource_id: 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: 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"
 }
 ]
}

Други seeded събития за контейнери

container_remove_lots
container_added_to_node
container_removed_from_node

Потвърдете излъчването във вашето внедряване, ако разчитате на тях.

Integrations

`integration_create` / `integration_update` / `integration_delete`

resource_name: integrations
resource_id: id на интеграцията

data — запис на интеграция: id, name, basic_auth_username, description, disabled, removed, is_system_integrations, …

Третирайте credentials в payload-ите като чувствителни.

Plant control

`inventory_cell_start`

plant_node_id: възел на завода на изходната клетка
roasthubs_zone_id: зона на изходната клетка

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`

Същата обвивка като при 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: възел на завода на клетката
roasthubs_zone_id: зона

data:

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

actualCellWeight спрямо correctedCellWeight зависи от пътя на корекцията.

`skip_cell_dosing_order` / `resolve_cell_not_found` / `cancel_dosing_order`

roasthubs_zone_id: обикновено 2 (roast)

data — клиентски контролен пакет (scalePlantNodeId, recipeId, zone, chosenCells, …).

`dumping_green_lot_fully_finished` / `dumping_green_lot_partially_finished`

roasthubs_zone_id: зона на dump

data:

{ "fullyDumped": true }

`lot_dump_fully_finished` / `lot_dump_partially_finished`

roasthubs_zone_id: изходна зона

data:

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

`scale_validation`

resource_name: lots
resource_id: id на свързаната партида

data — запис на свързаната партида към момента на валидацията.

Други seeded събития за plant-control

Id на събитие	Описание
`component_skip`	Пропускане на компонент от dosing-order
`coponent_switch`	Смяна на компонент от dosing-order
`dumping_green_start`	Dumping е започнал
`manual_control_running`	Активът работи (ръчно управление)
`manual_control_not_running`	Активът не работи (ръчно управление)
`manual_mode_on`	Активът е превключен в ръчен режим
`manual_mode_off`	Активът е превключен в автоматичен режим
`production_plan_start`	Производственият план е стартиран
`production_plan_stop`	Производственият план е спрян
`switching_cell_dosing_order`	Смяна на клетка след flow alarm
`tag_update`	Обновяване на таг
`auto_cell_selection`	Автоматичен избор на клетка

System

`user_comment`

resource_name: напр. contracts
resource_id: id на свързания ресурс

data:

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

`user_log_in` / `user_log_out`

Вход / изход на потребител.

Seeded за уебхукове; потвърдете излъчването във вашето внедряване, ако разчитате на тях.

Plant nodes

`plant_node_update`

resource_name: plant_nodes
resource_id: id на възела на завода

data — възел на завода: id, name, plant_node_type_id, capacity_kg, roasthubs_zone_id, is_blocked_input, is_blocked_output, properties, …

Пълен индекс на типовете събития

Конфигурируеми за уебхук типове (enable_webhook: true в seed).

Индекс Lots

Id на събитие	Описание
`lot_create`	Създаване на партида
`lot_update`	Обновяване на партида
`lot_delete`	Изтриване на партида

Също се излъчват: lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail.

Индекс Productions

Id на събитие	Описание
`production_create`	Създаване на продукция
`production_update`	Обновяване на продукция
`production_delete`	Изтриване на продукция

Индекс Recipes

Id на събитие	Описание
`recipe_create`	Създаване на рецепта
`recipe_update`	Обновяване на рецепта
`recipe_delete`	Изтриване на рецепта
`bulk_exchange_recipe_component`	Масова смяна на компонент на рецепта

Индекс Sales

Id на събитие	Описание
`sale_create`	Създаване на продажба
`sale_update`	Обновяване на продажба
`sale_lines_create`	Създаване на ред на продажба
`sale_lines_update`	Обновяване на ред на продажба

Индекс Products

Id на събитие	Описание
`product_create`	Създаване на продукт
`product_update`	Обновяване на продукт
`product_process_stage_create`	Създаване на етап от процеса на продукт
`product_process_stage_update`	Обновяване на етап от процеса на продукт

Индекс Contracts & call-offs

Id на събитие	Описание
`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

Id на събитие	Описание
`site_create`	Създаване на сайт
`site_update`	Обновяване на сайт

Индекс Targets

Id на събитие	Описание
`target_create`	Създаване на цел
`target_update`	Обновяване на цел
`target_delete`	Изтриване на цел

Индекс Returns

Id на събитие	Описание
`return_create`	Създаване на връщане
`return_update`	Обновяване на връщане
`return_add_lot`	Добавяне на партида към връщане
`return_remove_lot`	Премахване на партида от връщане

Индекс Containers

Id на събитие	Описание
`container_creation`	Създаване на контейнер (UI id; кодът може да излъчва `container_create`)
`container_update`	Обновяване на контейнер
`container_deletion`	Изтриване на контейнер (UI id; кодът може да излъчва `container_delete`)
`container_remove_lots`	Изчистване на партиди от контейнер
`container_added_to_node`	Контейнерът е свързан с възел на завода
`container_removed_from_node`	Контейнерът е разкачен от възел на завода

Също се излъчва: container_history_added.

Индекс Integrations

Id на събитие	Описание
`integration_create`	Създаване на интеграция
`integration_update`	Обновяване на интеграция
`integration_delete`	Изтриване на интеграция

Индекс Plant control

Id на събитие	Описание
`auto_cell_selection`	Автоматичен избор на клетка
`cancel_dosing_order`	Отмяна на цяла dosing order
`cell_theoretical_weight_correction`	Теоретична корекция на теглото на клетка
`component_skip`	Пропускане на компонент от dosing-order
`coponent_switch`	Смяна на компонент от dosing-order
`dumping_green_start`	Dumping е започнал
`dumping_green_lot_fully_finished`	Green dump; партидата е напълно разтоварена
`dumping_green_lot_partially_finished`	Green dump; партидата е частично разтоварена
`lot_dump_fully_finished`	Dump спрян; партидата е напълно изпразнена
`lot_dump_partially_finished`	Dump спрян; партидата е частично изпразнена
`inventory_cell_start`	Инвентаризацията на клетка е стартирана
`inventory_cell_stop`	Инвентаризацията на клетка е спряна
`manual_control_running`	Ръчното управление работи
`manual_control_not_running`	Ръчното управление не работи
`manual_mode_on`	Ръчен режим включен
`manual_mode_off`	Автоматичен режим включен
`production_plan_start`	Производственият план е стартиран
`production_plan_stop`	Производственият план е спрян
`resolve_cell_not_found`	Разрешаване на липсващ компонент на клетка
`scale_validation`	Валидация на везна
`skip_cell_dosing_order`	Пропускане на cell dosing order
`switching_cell_dosing_order`	Смяна на клетка за dosing order
`tag_update`	Обновяване на таг

Също се излъчва: plant_node_update.

Индекс System

Id на събитие	Описание
`user_log_in`	Потребителят влиза
`user_log_out`	Потребителят излиза
`user_comment`	Потребителски коментар

Примерен приемник

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

Отговорете с 2xx, за да третира Roasthubs доставката като успешна. Отговори, различни от 2xx, задействат повторни опити според retry_count на уебхука.

Обобщение — какво се задейства къде
Доставка
Обща обвивка
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
Пълен индекс на типовете събития
Примерен приемник

Обобщение — какво се задейства къде​

Lots​

Productions​

Recipes​

Sales​

Products​

Contracts & call-offs​

Sites​

Targets​

Returns​

Containers​

Integrations​

Plant control​

Plant nodes​

System​

Доставка​

Обща обвивка​

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​

Други seeded събития за контейнери​

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​

Други seeded събития за plant-control​

System​

user_comment​

user_log_in / user_log_out​

Plant nodes​

plant_node_update​

Пълен индекс на типовете събития​

Индекс Lots​

Индекс Productions​

Индекс Recipes​

Индекс Sales​

Индекс Products​

Индекс Contracts & call-offs​

Индекс Sites​

Индекс Targets​

Индекс Returns​

Индекс Containers​

Индекс Integrations​

Обобщение — какво се задейства къде

Lots

Productions

Recipes

Sales

Products

Contracts & call-offs

Sites

Targets

Returns

Containers

Integrations

Plant control

Plant nodes

System

Доставка

Обща обвивка

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`

Други seeded събития за контейнери

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`

Други seeded събития за plant-control

System

`user_comment`

`user_log_in` / `user_log_out`

Plant nodes

`plant_node_update`

Пълен индекс на типовете събития

Индекс Lots

Индекс Productions

Индекс Recipes

Индекс Sales

Индекс Products

Индекс Contracts & call-offs

Индекс Sites

Индекс Targets

Индекс Returns

Индекс Containers

Индекс Integrations