Eventos webhook de Roasthubs

Los webhooks salientes hacen POST de JSON a la URL configurada cuando ocurre un evento coincidente.

Configure en System → Webhooks (un webhook por tipo de evento).

Cómo usar esto en Notion

Importe este archivo con Notion → Import → Markdown, o pegue el contenido en una página nueva.

Convierta cada encabezado de grupo (Lots, Sales, …) en un Toggle heading si quiere un documento plegable.

Opcionalmente convierta la sección de resumen en una base de datos de Notion (una fila por grupo).

Resumen — qué se dispara dónde

Todos los webhooks usan el mismo sobre. El contenido específico del evento siempre está en data. Use el id de nivel superior como clave de idempotencia.

Lots

Dónde: Crear/actualizar lote, evaluación de QC, procesamiento de tueste
Eventos: lot_create, lot_update, lot_delete, lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail
Datos típicos: Registro de lote, o resultado de objetivo / QC

Productions

Dónde: API de planificación de producción
Eventos: production_create, production_update, production_delete
Datos típicos: Registro de producción

Recipes

Dónde: CRUD de recetas + intercambio masivo de componentes
Eventos: recipe_create, recipe_update, recipe_delete, bulk_exchange_recipe_component
Datos típicos: Registro de receta, o cuerpo de la petición de intercambio

Sales

Dónde: API de ventas / líneas de venta + procesador de lotes de tueste
Eventos: sale_create, sale_update, sale_lines_create, sale_lines_update
Datos típicos: Registro de venta o de línea de venta

Products

Dónde: API de productos
Eventos: product_create, product_update, product_process_stage_create, product_process_stage_update
Datos típicos: Campos de producto, o { product_id, recipe_id, recipe_name }

Contracts & call-offs

Dónde: APIs de compras / contratos + cron / actualizaciones de peso de lote
Eventos: contracts_create, contracts_update, contracts_call_offs_*, contracts_call_offs_lines_*
Datos típicos: Registro de contrato, call-off o línea

Sites

Dónde: API de sites
Eventos: site_create, site_update
Datos típicos: Registro de site

Targets

Dónde: API de objetivos de laboratorio
Eventos: target_create, target_update, target_delete
Datos típicos: Registro de objetivo

Returns

Dónde: API de devoluciones
Eventos: return_create, return_update, return_add_lot, return_remove_lot
Datos típicos: Registro de devolución, o carga de añadir/quitar lote

Containers

Dónde: API de contenedores + helpers OPC
Eventos: container_create, container_update, container_delete, container_history_added, más variantes sembradas
Datos típicos: { container } o entradas de historial

Integrations

Dónde: API de integraciones
Eventos: integration_create, integration_update, integration_delete
Datos típicos: Registro de integración

Plant control

Dónde: OPC-UA / UI de planta (dosificación, dump, inventario, básculas)
Eventos: Dump, inventario, omitir/cancelar/resolver dosificación, corrección de peso de celda, validación de báscula, modo/control
Datos típicos: Paquetes específicos de la acción o cargas de celda/dump

Plant nodes

Dónde: API de actualización de nodo de planta
Eventos: plant_node_update
Datos típicos: Registro de nodo de planta

System

Dónde: Auth / comentarios
Eventos: user_log_in, user_log_out, user_comment
Datos típicos: Texto del comentario, o carga mínima de inicio de sesión

Nota: Los grupos estilo CRUD anteriores se emiten activamente desde el código de la aplicación. Varios eventos de control de planta y auth (user_log_in / user_log_out, manual_mode_*, tag_update, production_plan_*, …) son seleccionables en la UI de Webhooks pero pueden no dispararse hasta que esa ruta los emita.

Entrega

Comportamiento	Detalle
Method	`POST`
Content-Type	`application/json`
Retries	0–10, backoff exponencial (`2^attempt × 1000` ms)
Idempotency	`id` de nivel superior

Sobre común

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

Campo	Tipo	Obligatorio	Descripción
`id`	number	yes	Id del registro de evento (clave de idempotencia)
`type_id`	string	yes	Identificador del tipo de evento
`user_id`	number	yes	Usuario que actúa (`0` / `1` = sistema)
`resource_id`	number	no	Id del recurso relacionado
`resource_name`	string	no	Nombre del recurso / tabla
`plant_node_id`	number	no	Nodo de planta relacionado
`roasthubs_zone_id`	number	no	Zona relacionada
`data`	object	no	Carga específica del evento

Los campos omitidos pueden aparecer como null en eventos almacenados.

Lots

`lot_create`

Creación de un lote.

resource_name: lots (cuando está definido)
resource_id: id del lote
roasthubs_zone_id: zona del lote

data — registro del lote creado:

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

Actualización de un lote (p. ej. tras el tueste).

resource_name: lots
resource_id: id del lote

data — registro del lote actualizado.

`lot_delete`

Eliminación de un lote.

Sembrado para webhooks; confirme la emisión en su despliegue si depende de él.

`lot_target_pass` / `lot_target_fail`

Se evaluó un objetivo de QC en un lote.

resource_id: id del lote
roasthubs_zone_id: zona del lote

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

Variante más estrecha de lot_target_pass:

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

`lot_qc_pass` / `lot_qc_fail`

Todos los objetivos de un lote evaluados; resultado global de QC.

resource_id: id del lote
roasthubs_zone_id: zona del lote

data — registro del lote incluyendo lots_targets relacionados.

Productions

`production_create` / `production_update` / `production_delete`

resource_id: id de la producción
roasthubs_zone_id: zona de la producción
plant_node_id: nodo de planta de realisation

data — registro de producción: 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 la receta
roasthubs_zone_id: zona de destino

data — registro de receta, o en intercambio masivo:

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

Eliminación de una receta.

Sembrado para webhooks; confirme la emisión en su despliegue si depende de él.

`bulk_exchange_recipe_component`

resource_name: recipes
resource_id: id de la receta componente que se intercambia
roasthubs_zone_id: normalmente 2

data — cuerpo de la petición de intercambio masivo (recetas seleccionadas, id del café de intercambio, id de usuario, …).

Sales

`sale_create` / `sale_update`

resource_name: sales
resource_id: id de la venta

data — registro de venta: id, id_tag, customer_id, customer_name, status, due_date, erp_id, reference, …

`sale_lines_create`

resource_name: sales
resource_id: id de la venta padre

data — línea de venta: id, sale_id, product_id, product_name, qty, weight_ordered, weight_remaining, status, …

`sale_lines_update`

resource_name: sales o sales_lines
resource_id: id de venta o de línea de venta (varía según el llamador)

data — registro de línea de venta actualizado.

Products

`product_create` / `product_update`

resource_name: products
resource_id: id del producto

data — campos del producto: id_tag, reference, name, is_producable, mass_smallest_unit, qty_per_product_smallest_unit, price, … (a menudo incluyendo etapas de proceso).

`product_process_stage_create`

resource_id: id del producto
resource_name: products (cuando está definido)

data:

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

`product_process_stage_update`

Actualización de una etapa de proceso de producto.

Sembrado para webhooks; confirme la emisión en su despliegue si depende de él.

Contracts & call-offs

`contracts_create` / `contracts_update`

resource_name: contracts
resource_id: id del contrato

data — registro de contrato o actualización parcial: 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 del call-off

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

`contracts_call_offs_lines_create` / `contracts_call_offs_lines_update` / `contracts_call_offs_lines_delete`

resource_name: contracts_call_offs o contracts_call_offs_lines
resource_id: id del call-off (o id de línea en algunas actualizaciones)

data — línea 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 del site

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

Targets

Ids de evento en la UI: target_create, target_update, target_delete.

El código puede emitir targets_create, targets_update, targets_delete. Coincida el type_id de una carga real de prueba de webhook.

resource_name: targets
resource_id: id del objetivo

data — registro de objetivo: 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 la devolución

data — registro de devolución: 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

Los ids de UI / seed incluyen container_creation, container_deletion. Los eventos create/delete emitidos usan container_create / container_delete. Coincida el type_id real.

`container_create` / `container_update` / `container_delete`

resource_name: containers
resource_id: id del contenedor

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 del contenedor

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

Otros eventos de contenedor sembrados

container_remove_lots
container_added_to_node
container_removed_from_node

Confirme la emisión en su despliegue si depende de ellos.

Integrations

`integration_create` / `integration_update` / `integration_delete`

resource_name: integrations
resource_id: id de la integración

data — registro de integración: id, name, basic_auth_username, description, disabled, removed, is_system_integrations, …

Trate las credenciales en las cargas como sensibles.

Plant control

`inventory_cell_start`

plant_node_id: nodo de planta de la celda origen
roasthubs_zone_id: zona de la celda origen

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`

Mismo sobre que el inicio.

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: nodo de planta de la celda
roasthubs_zone_id: zona

data:

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

actualCellWeight vs correctedCellWeight depende de la ruta de corrección.

`skip_cell_dosing_order` / `resolve_cell_not_found` / `cancel_dosing_order`

roasthubs_zone_id: normalmente 2 (roast)

data — paquete de control del cliente (scalePlantNodeId, recipeId, zone, chosenCells, …).

`dumping_green_lot_fully_finished` / `dumping_green_lot_partially_finished`

roasthubs_zone_id: zona del dump

data:

{ "fullyDumped": true }

`lot_dump_fully_finished` / `lot_dump_partially_finished`

roasthubs_zone_id: zona origen

data:

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

`scale_validation`

resource_name: lots
resource_id: id del lote relacionado

data — registro del lote relacionado en el momento de la validación.

Otros eventos de control de planta sembrados

Event id	Description
`component_skip`	Omitir un componente de orden de dosificación
`coponent_switch`	Cambiar un componente de orden de dosificación
`dumping_green_start`	Dump iniciado
`manual_control_running`	Activo en marcha (control manual)
`manual_control_not_running`	Activo parado (control manual)
`manual_mode_on`	Activo pasado a modo manual
`manual_mode_off`	Activo pasado a modo automático
`production_plan_start`	Plan de producción iniciado
`production_plan_stop`	Plan de producción detenido
`switching_cell_dosing_order`	Cambiar celda tras alarma de flujo
`tag_update`	Actualización de etiqueta
`auto_cell_selection`	Selección automática de celda

System

`user_comment`

resource_name: p. ej. contracts
resource_id: id del recurso relacionado

data:

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

`user_log_in` / `user_log_out`

Inicio / cierre de sesión de usuario.

Sembrado para webhooks; confirme la emisión en su despliegue si depende de ellos.

Plant nodes

`plant_node_update`

resource_name: plant_nodes
resource_id: id del nodo de planta

data — nodo de planta: id, name, plant_node_type_id, capacity_kg, roasthubs_zone_id, is_blocked_input, is_blocked_output, properties, …

Índice completo de tipos de evento

Tipos configurables por webhook (enable_webhook: true en el seed).

Índice Lots

Event id	Description
`lot_create`	Crear lote
`lot_update`	Actualizar lote
`lot_delete`	Eliminar lote

También emitidos: lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail.

Índice Productions

Event id	Description
`production_create`	Crear producción
`production_update`	Actualizar producción
`production_delete`	Eliminar producción

Índice Recipes

Event id	Description
`recipe_create`	Crear receta
`recipe_update`	Actualizar receta
`recipe_delete`	Eliminar receta
`bulk_exchange_recipe_component`	Intercambio masivo de un componente de receta

Índice Sales

Event id	Description
`sale_create`	Crear venta
`sale_update`	Actualizar venta
`sale_lines_create`	Crear línea de venta
`sale_lines_update`	Actualizar línea de venta

Índice Products

Event id	Description
`product_create`	Crear producto
`product_update`	Actualizar producto
`product_process_stage_create`	Crear etapa de proceso de producto
`product_process_stage_update`	Actualizar etapa de proceso de producto

Índice Contracts & call-offs

Event id	Description
`contracts_create`	Crear contrato
`contracts_update`	Actualizar contrato
`contracts_call_offs_create`	Crear call-off
`contracts_call_offs_update`	Actualizar call-off
`contracts_call_offs_lines_create`	Crear línea de call-off
`contracts_call_offs_lines_update`	Actualizar línea de call-off
`contracts_call_offs_lines_delete`	Eliminar línea de call-off

Índice Sites

Event id	Description
`site_create`	Crear site
`site_update`	Actualizar site

Índice Targets

Event id	Description
`target_create`	Crear objetivo
`target_update`	Actualizar objetivo
`target_delete`	Eliminar objetivo

Índice Returns

Event id	Description
`return_create`	Crear devolución
`return_update`	Actualizar devolución
`return_add_lot`	Añadir lote a la devolución
`return_remove_lot`	Quitar lote de la devolución

Índice Containers

Event id	Description
`container_creation`	Crear contenedor (id de UI; el código puede emitir `container_create`)
`container_update`	Actualizar contenedor
`container_deletion`	Eliminar contenedor (id de UI; el código puede emitir `container_delete`)
`container_remove_lots`	Vaciar lotes del contenedor
`container_added_to_node`	Contenedor vinculado a nodo de planta
`container_removed_from_node`	Contenedor desvinculado de nodo de planta

También emitido: container_history_added.

Índice Integrations

Event id	Description
`integration_create`	Crear integración
`integration_update`	Actualizar integración
`integration_delete`	Eliminar integración

Índice Plant control

Event id	Description
`auto_cell_selection`	Selección automática de celda
`cancel_dosing_order`	Cancelar orden de dosificación completa
`cell_theoretical_weight_correction`	Corrección teórica del peso de celda
`component_skip`	Omitir componente de orden de dosificación
`coponent_switch`	Cambiar componente de orden de dosificación
`dumping_green_start`	Dump iniciado
`dumping_green_lot_fully_finished`	Dump verde; lote completamente vaciado
`dumping_green_lot_partially_finished`	Dump verde; lote parcialmente vaciado
`lot_dump_fully_finished`	Dump detenido; lote completamente vaciado
`lot_dump_partially_finished`	Dump detenido; lote parcialmente vaciado
`inventory_cell_start`	Inventariado de celda iniciado
`inventory_cell_stop`	Inventariado de celda detenido
`manual_control_running`	Control manual en marcha
`manual_control_not_running`	Control manual parado
`manual_mode_on`	Modo manual activado
`manual_mode_off`	Modo automático activado
`production_plan_start`	Plan de producción iniciado
`production_plan_stop`	Plan de producción detenido
`resolve_cell_not_found`	Resolver componente de celda ausente
`scale_validation`	Validación de báscula
`skip_cell_dosing_order`	Omitir orden de dosificación de celda
`switching_cell_dosing_order`	Cambiar celda para orden de dosificación
`tag_update`	Actualización de etiqueta

También emitido: plant_node_update.

Índice System

Event id	Description
`user_log_in`	El usuario inicia sesión
`user_log_out`	El usuario cierra sesión
`user_comment`	Comentario de usuario

Receptor de ejemplo

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

Responda con 2xx para que Roasthubs trate la entrega como correcta. Las respuestas no 2xx disparan reintentos según el retry_count del webhook.

Resumen — qué se dispara dónde
Entrega
Sobre común
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
Índice completo de tipos de evento
Receptor de ejemplo

Resumen — qué se dispara dónde​

Lots​

Productions​

Recipes​

Sales​

Products​

Contracts & call-offs​

Sites​

Targets​

Returns​

Containers​

Integrations​

Plant control​

Plant nodes​

System​

Entrega​

Sobre común​

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​

Otros eventos de contenedor sembrados​

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​

Otros eventos de control de planta sembrados​

System​

user_comment​

user_log_in / user_log_out​

Plant nodes​

plant_node_update​

Índice completo de tipos de evento​

Índice Lots​

Índice Productions​

Índice Recipes​

Índice Sales​

Índice Products​

Índice Contracts & call-offs​

Índice Sites​

Índice Targets​

Índice Returns​

Índice Containers​

Índice Integrations​

Resumen — qué se dispara dónde

Lots

Productions

Recipes

Sales

Products

Contracts & call-offs

Sites

Targets

Returns

Containers

Integrations

Plant control

Plant nodes

System

Entrega

Sobre común

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`

Otros eventos de contenedor sembrados

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`

Otros eventos de control de planta sembrados

System

`user_comment`

`user_log_in` / `user_log_out`

Plant nodes

`plant_node_update`

Índice completo de tipos de evento

Índice Lots

Índice Productions

Índice Recipes

Índice Sales

Índice Products

Índice Contracts & call-offs

Índice Sites

Índice Targets

Índice Returns

Índice Containers

Índice Integrations