Roasthubs Webhook-Ereignisse
Ausgehende Webhooks senden per POST JSON an Ihre konfigurierte URL, wenn ein passendes Ereignis eintritt.
Konfiguration unter System → Webhooks (ein Webhook pro Ereignistyp).
So nutzen Sie das in Notion
- Importieren Sie diese Datei über Notion → Import → Markdown, oder fügen Sie den Inhalt in eine neue Seite ein.
- Wandeln Sie jede Gruppenüberschrift (Chargen, Verkauf, …) in eine Toggle-Überschrift um, wenn Sie ein einklappbares Dokument möchten.
- Optional wandeln Sie den Zusammenfassungsabschnitt in eine Notion-Datenbank um (eine Zeile pro Gruppe).
Zusammenfassung — was wo auslöst
Jeder Webhook verwendet dieselbe Hülle. Ereignisspezifischer Inhalt liegt immer in data. Nutzen Sie die Top-Level-id als Idempotenzschlüssel.
Chargen
- Wo: Charge anlegen/aktualisieren, QC-Bewertung, Röstverarbeitung
- Ereignisse:
lot_create,lot_update,lot_delete,lot_target_pass,lot_target_fail,lot_qc_pass,lot_qc_fail - Typische Daten: Chargendatensatz oder Ziel- / QC-Ergebnis
Produktionen
- Wo: Produktionsplanungs-API
- Ereignisse:
production_create,production_update,production_delete - Typische Daten: Produktionsdatensatz
Rezepte
- Wo: Rezept-CRUD + Massen-Komponentenaustausch
- Ereignisse:
recipe_create,recipe_update,recipe_delete,bulk_exchange_recipe_component - Typische Daten: Rezeptdatensatz oder Austausch-Request-Body
Verkauf
- Wo: Verkaufs- / Verkaufspositions-API + Röstcharge-Prozessor
- Ereignisse:
sale_create,sale_update,sale_lines_create,sale_lines_update - Typische Daten: Verkaufs- oder Verkaufspositionsdatensatz
Produkte
- Wo: Produkte-API
- Ereignisse:
product_create,product_update,product_process_stage_create,product_process_stage_update - Typische Daten: Produktfelder oder
{ product_id, recipe_id, recipe_name }
Verträge & Abrufe
- Wo: Beschaffungs- / Vertrags-APIs + Cron / Chargengewichts-Updates
- Ereignisse:
contracts_create,contracts_update,contracts_call_offs_*,contracts_call_offs_lines_* - Typische Daten: Vertrags-, Abruf- oder Positionsdatensatz
Standorte
- Wo: Sites-API
- Ereignisse:
site_create,site_update - Typische Daten: Standort-Datensatz
Ziele
- Wo: Labor-Ziele-API
- Ereignisse:
target_create,target_update,target_delete - Typische Daten: Zieldatensatz
Retouren
- Wo: Returns-API
- Ereignisse:
return_create,return_update,return_add_lot,return_remove_lot - Typische Daten: Retouren-Datensatz oder Charge hinzufügen/entfernen-Payload
Behälter
- Wo: Containers-API + OPC-Helfer
- Ereignisse:
container_create,container_update,container_delete,container_history_added, plus geseedete Varianten - Typische Daten:
{ container }oder Historie-Einträge
Integrationen
- Wo: Integrations-API
- Ereignisse:
integration_create,integration_update,integration_delete - Typische Daten: Integrations-Datensatz
Anlagensteuerung
- Wo: OPC-UA / Anlagen-UI (Dosierung, Entladen, Inventar, Waagen)
- Ereignisse: Entladen, Inventar, Dosierung überspringen/abbrechen/auflösen, Zellengewichtskorrektur, Waagenvalidierung, Modus/Steuerung
- Typische Daten: aktionsspezifische Pakete oder Zellen-/Entlade-Payloads
Anlagenknoten
- Wo: Anlagenknoten-Update-API
- Ereignisse:
plant_node_update - Typische Daten: Anlagenknoten-Datensatz
System
- Wo: Auth / Kommentare
- Ereignisse:
user_log_in,user_log_out,user_comment - Typische Daten: Kommentartext oder minimales Login-Payload
Hinweis: CRUD-artige Gruppen oben werden aktiv aus Anwendungscode ausgelöst. Mehrere Anlagensteuerungs- und Auth-Ereignisse (
user_log_in/user_log_out,manual_mode_*,tag_update,production_plan_*, …) sind in der Webhooks-UI auswählbar, feuern aber möglicherweise erst, wenn dieser Pfad sie auslöst.
Zustellung
| Verhalten | Detail |
|---|---|
| Methode | POST |
| Content-Type | application/json |
| Retries | 0–10, exponentielles Backoff (2^attempt × 1000 ms) |
| Idempotenz | Top-Level-id |
Gemeinsame Hülle
{
"id": 12345,
"type_id": "lot_create",
"user_id": 1,
"resource_id": 42,
"resource_name": "lots",
"plant_node_id": null,
"roasthubs_zone_id": 1,
"data": {}
}
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
id | number | ja | Ereignis-Log-ID (Idempotenzschlüssel) |
type_id | string | ja | Ereignistyp-Kennung |
user_id | number | ja | Handelnder Benutzer (0 / 1 = System) |
resource_id | number | nein | Zugehörige Ressourcen-ID |
resource_name | string | nein | Ressourcen- / Tabellenname |
plant_node_id | number | nein | Zugehöriger Anlagenknoten |
roasthubs_zone_id | number | nein | Zugehörige Zone |
data | object | nein | Ereignisspezifischer Payload |
Weggelassene Felder können in gespeicherten Ereignissen als null erscheinen.
Chargen
lot_create
Anlage einer Charge.
resource_name:lots(wenn gesetzt)resource_id: Charge-IDroasthubs_zone_id: Charge-Zone
data — angelegter Chargendatensatz:
{
"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
Aktualisierung einer Charge (z. B. nach dem Rösten).
resource_name:lotsresource_id: Charge-ID
data — aktualisierter Chargendatensatz.
lot_delete
Löschung einer Charge.
Für Webhooks geseedet; bestätigen Sie die Emission in Ihrer Installation, wenn Sie sich darauf verlassen.
lot_target_pass / lot_target_fail
Ein QC-Ziel an einer Charge wurde bewertet.
resource_id: Charge-IDroasthubs_zone_id: Charge-Zone
data — die targets-Zeile (id, parameter_id, lower_bound, upper_bound, recipe_id, …).
Engere lot_target_pass-Variante:
{ "status": "pass", "target_id": 7 }
lot_qc_pass / lot_qc_fail
Alle Ziele einer Charge bewertet; Gesamtergebnis der QC.
resource_id: Charge-IDroasthubs_zone_id: Charge-Zone
data — Chargendatensatz einschließlich zugehöriger lots_targets.
Produktionen
production_create / production_update / production_delete
resource_id: Produktions-IDroasthubs_zone_id: Produktionszoneplant_node_id: Realisierungs-Anlagenknoten
data — Produktionsdatensatz: id, name, recipe_id, batch_size_kg, batch_qty, status, type, due_date, product_id, order_line_id, …
Rezepte
recipe_create / recipe_update
resource_name:recipesresource_id: Rezept-IDroasthubs_zone_id: Zielzone
data — Rezeptdatensatz, oder bei Massen-Austausch:
{
"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
Löschung eines Rezepts.
Für Webhooks geseedet; bestätigen Sie die Emission in Ihrer Installation, wenn Sie sich darauf verlassen.
bulk_exchange_recipe_component
resource_name:recipesresource_id: Komponenten-Rezept-ID, die ausgetauscht wirdroasthubs_zone_id: typischerweise2
data — Request-Body des Massen-Austauschs (ausgewählte Rezepte, Austausch-Kaffee-ID, Benutzer-ID, …).
Verkauf
sale_create / sale_update
resource_name:salesresource_id: Verkaufs-ID
data — Verkaufsdatensatz: id, id_tag, customer_id, customer_name, status, due_date, erp_id, reference, …
sale_lines_create
resource_name:salesresource_id: übergeordnete Verkaufs-ID
data — Verkaufsposition: id, sale_id, product_id, product_name, qty, weight_ordered, weight_remaining, status, …
sale_lines_update
resource_name:salesodersales_linesresource_id: Verkaufs-ID oder Positions-ID (variiert je nach Aufrufer)
data — aktualisierter Verkaufspositionsdatensatz.
Produkte
product_create / product_update
resource_name:productsresource_id: Produkt-ID
data — Produktfelder: id_tag, reference, name, is_producable, mass_smallest_unit, qty_per_product_smallest_unit, price, … (oft einschließlich Prozessstufen).
product_process_stage_create
resource_id: Produkt-IDresource_name:products(wenn gesetzt)
data:
{
"product_id": 10,
"recipe_id": 5,
"recipe_name": "Espresso blend"
}
product_process_stage_update
Aktualisierung einer Produkt-Prozessstufe.
Für Webhooks geseedet; bestätigen Sie die Emission in Ihrer Installation, wenn Sie sich darauf verlassen.
Verträge & Abrufe
contracts_create / contracts_update
resource_name:contractsresource_id: Vertrags-ID
data — Vertragsdatensatz oder Teil-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_offsresource_id: Abruf-ID
data — Abruf-Datensatz: id, id_tag, call_off_number, supplier_id, status, ordered_receiving_date, … — oder { "status": "delivered" }.
contracts_call_offs_lines_create / contracts_call_offs_lines_update / contracts_call_offs_lines_delete
resource_name:contracts_call_offsodercontracts_call_offs_linesresource_id: Abruf-ID (oder Positions-ID bei manchen Updates)
data — Abrufposition: id, contract_id, contract_call_off_id, quantity, status, eudr_dds_number, …
Standorte
site_create / site_update
resource_name:sitesresource_id: Standort-ID
data — Standort-Datensatz: id, name, address_line1, city, country, time_zone, site_status, unit_system, …
Ziele
UI-Ereignis-IDs: target_create, target_update, target_delete.
Code kann targets_create, targets_update, targets_delete auslösen. Vergleichen Sie die type_id mit einem echten Webhook-Test-Payload.
resource_name:targetsresource_id: Ziel-ID
data — Zieldatensatz: id, parameter_id, lower_bound, upper_bound, recipe_id, plant_node_id, applies_to_all_lots, removed, …
Retouren
return_create / return_update
resource_name:returnsresource_id: Retouren-ID
data — Retouren-Datensatz: 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
}
Behälter
UI- / Seed-IDs umfassen container_creation, container_deletion. Ausgelöste Create-/Delete-Ereignisse nutzen container_create / container_delete. Vergleichen Sie die echte type_id.
container_create / container_update / container_delete
resource_name:containersresource_id: Behälter-ID
data:
{
"container": {
"id": 1,
"reference": "BIN-01",
"status": "active",
"erp_id": null,
"capacity": 1000,
"allowed_maximum_usages": null
}
}
container_history_added
resource_name:containersresource_id: Behälter-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"
}
]
}
Weitere geseedete Behälter-Ereignisse
container_remove_lotscontainer_added_to_nodecontainer_removed_from_node
Bestätigen Sie die Emission in Ihrer Installation, wenn Sie sich darauf verlassen.
Integrationen
integration_create / integration_update / integration_delete
resource_name:integrationsresource_id: Integrations-ID
data — Integrations-Datensatz: id, name, basic_auth_username, description, disabled, removed, is_system_integrations, …
Behandeln Sie Anmeldedaten in Payloads als sensibel.
Anlagensteuerung
inventory_cell_start
plant_node_id: Quellzellen-Anlagenknotenroasthubs_zone_id: Zone der Quellzelle
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
Dieselbe Hülle wie beim 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: Zellen-Anlagenknotenroasthubs_zone_id: Zone
data:
{
"cellId": 3,
"initialCellWeight": 100,
"actualCellWeight": 0,
"correctedCellWeight": 95.2,
"initialCellLines": [],
"correctedCellLines": []
}
actualCellWeight vs. correctedCellWeight hängt vom Korrekturpfad ab.
skip_cell_dosing_order / resolve_cell_not_found / cancel_dosing_order
roasthubs_zone_id: typischerweise2(Rösten)
data — Client-Steuerungspaket (scalePlantNodeId, recipeId, zone, chosenCells, …).
dumping_green_lot_fully_finished / dumping_green_lot_partially_finished
roasthubs_zone_id: Entladezone
data:
{ "fullyDumped": true }
lot_dump_fully_finished / lot_dump_partially_finished
roasthubs_zone_id: Quellzone
data:
{
"sourcePlantNodeId": 7,
"sourceLotId": 42,
"resolvedSourceLotId": 42,
"lotFullyDumped": true,
"viaRealisationBufferStop": true
}
scale_validation
resource_name:lotsresource_id: zugehörige Charge-ID
data — zugehöriger Chargendatensatz zum Validierungszeitpunkt.
Weitere geseedete Anlagensteuerungs-Ereignisse
| Ereignis-ID | Beschreibung |
|---|---|
component_skip | Eine Dosierauftrags-Komponente überspringen |
coponent_switch | Eine Dosierauftrags-Komponente wechseln |
dumping_green_start | Entladen gestartet |
manual_control_running | Asset läuft (manuelle Steuerung) |
manual_control_not_running | Asset läuft nicht (manuelle Steuerung) |
manual_mode_on | Asset auf manuellen Modus umgeschaltet |
manual_mode_off | Asset auf Automatikmodus umgeschaltet |
production_plan_start | Produktionsplan gestartet |
production_plan_stop | Produktionsplan gestoppt |
switching_cell_dosing_order | Zelle nach Flow-Alarm wechseln |
tag_update | Tag-Update |
auto_cell_selection | Automatische Zellenauswahl |
System
user_comment
resource_name: z. B.contractsresource_id: zugehörige Ressourcen-ID
data:
{ "comment": "Human-readable comment text…" }
user_log_in / user_log_out
Benutzer-Login / -Logout.
Für Webhooks geseedet; bestätigen Sie die Emission in Ihrer Installation, wenn Sie sich darauf verlassen.
Anlagenknoten
plant_node_update
resource_name:plant_nodesresource_id: Anlagenknoten-ID
data — Anlagenknoten: id, name, plant_node_type_id, capacity_kg, roasthubs_zone_id, is_blocked_input, is_blocked_output, properties, …
Vollständiger Ereignistyp-Index
Webhook-konfigurierbare Typen (enable_webhook: true im Seed).
Chargen-Index
| Ereignis-ID | Beschreibung |
|---|---|
lot_create | Charge anlegen |
lot_update | Charge aktualisieren |
lot_delete | Charge löschen |
Außerdem ausgelöst: lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail.
Produktionen-Index
| Ereignis-ID | Beschreibung |
|---|---|
production_create | Produktion anlegen |
production_update | Produktion aktualisieren |
production_delete | Produktion löschen |
Rezepte-Index
| Ereignis-ID | Beschreibung |
|---|---|
recipe_create | Rezept anlegen |
recipe_update | Rezept aktualisieren |
recipe_delete | Rezept löschen |
bulk_exchange_recipe_component | Massen-Austausch einer Rezeptkomponente |
Verkauf-Index
| Ereignis-ID | Beschreibung |
|---|---|
sale_create | Verkauf anlegen |
sale_update | Verkauf aktualisieren |
sale_lines_create | Verkaufsposition anlegen |
sale_lines_update | Verkaufsposition aktualisieren |
Produkte-Index
| Ereignis-ID | Beschreibung |
|---|---|
product_create | Produkt anlegen |
product_update | Produkt aktualisieren |
product_process_stage_create | Produkt-Prozessstufe anlegen |
product_process_stage_update | Produkt-Prozessstufe aktualisieren |
Verträge- & Abrufe-Index
| Ereignis-ID | Beschreibung |
|---|---|
contracts_create | Vertrag anlegen |
contracts_update | Vertrag aktualisieren |
contracts_call_offs_create | Abruf anlegen |
contracts_call_offs_update | Abruf aktualisieren |
contracts_call_offs_lines_create | Abrufposition anlegen |
contracts_call_offs_lines_update | Abrufposition aktualisieren |
contracts_call_offs_lines_delete | Abrufposition löschen |
Standorte-Index
| Ereignis-ID | Beschreibung |
|---|---|
site_create | Standort anlegen |
site_update | Standort aktualisieren |
Ziele-Index
| Ereignis-ID | Beschreibung |
|---|---|
target_create | Ziel anlegen |
target_update | Ziel aktualisieren |
target_delete | Ziel löschen |
Retouren-Index
| Ereignis-ID | Beschreibung |
|---|---|
return_create | Retoure anlegen |
return_update | Retoure aktualisieren |
return_add_lot | Charge zur Retoure hinzufügen |
return_remove_lot | Charge aus Retoure entfernen |
Behälter-Index
| Ereignis-ID | Beschreibung |
|---|---|
container_creation | Behälter anlegen (UI-ID; Code kann container_create auslösen) |
container_update | Behälter aktualisieren |
container_deletion | Behälter löschen (UI-ID; Code kann container_delete auslösen) |
container_remove_lots | Chargen aus Behälter entfernen |
container_added_to_node | Behälter mit Anlagenknoten verknüpft |
container_removed_from_node | Behälter von Anlagenknoten getrennt |
Außerdem ausgelöst: container_history_added.
Integrationen-Index
| Ereignis-ID | Beschreibung |
|---|---|
integration_create | Integration anlegen |
integration_update | Integration aktualisieren |
integration_delete | Integration löschen |
Anlagensteuerung-Index
| Ereignis-ID | Beschreibung |
|---|---|
auto_cell_selection | Automatische Zellenauswahl |
cancel_dosing_order | Gesamten Dosierauftrag abbrechen |
cell_theoretical_weight_correction | Theoretische Zellengewichtskorrektur |
component_skip | Dosierauftrags-Komponente überspringen |
coponent_switch | Dosierauftrags-Komponente wechseln |
dumping_green_start | Entladen gestartet |
dumping_green_lot_fully_finished | Rohkaffee-Entladung; Charge vollständig entladen |
dumping_green_lot_partially_finished | Rohkaffee-Entladung; Charge teilweise entladen |
lot_dump_fully_finished | Entladen gestoppt; Charge vollständig geleert |
lot_dump_partially_finished | Entladen gestoppt; Charge teilweise geleert |
inventory_cell_start | Zelleninventarisierung gestartet |
inventory_cell_stop | Zelleninventarisierung gestoppt |
manual_control_running | Manuelle Steuerung läuft |
manual_control_not_running | Manuelle Steuerung läuft nicht |
manual_mode_on | Manueller Modus ein |
manual_mode_off | Automatikmodus ein |
production_plan_start | Produktionsplan gestartet |
production_plan_stop | Produktionsplan gestoppt |
resolve_cell_not_found | Fehlende Zellenkomponente auflösen |
scale_validation | Waagenvalidierung |
skip_cell_dosing_order | Zellen-Dosierauftrag überspringen |
switching_cell_dosing_order | Zelle für Dosierauftrag wechseln |
tag_update | Tag-Update |
Außerdem ausgelöst: plant_node_update.
System-Index
| Ereignis-ID | Beschreibung |
|---|---|
user_log_in | Benutzer meldet sich an |
user_log_out | Benutzer meldet sich ab |
user_comment | Benutzerkommentar |
Beispiel-Empfänger
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"
}
}
Antworten Sie mit 2xx, damit Roasthubs die Zustellung als erfolgreich wertet. Nicht-2xx-Antworten lösen Retries gemäß retry_count des Webhooks aus.