Zum Hauptinhalt springen

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

  1. Importieren Sie diese Datei über Notion → Import → Markdown, oder fügen Sie den Inhalt in eine neue Seite ein.
  2. Wandeln Sie jede Gruppenüberschrift (Chargen, Verkauf, …) in eine Toggle-Überschrift um, wenn Sie ein einklappbares Dokument möchten.
  3. 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

VerhaltenDetail
MethodePOST
Content-Typeapplication/json
Retries0–10, exponentielles Backoff (2^attempt × 1000 ms)
IdempotenzTop-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": {}
}
FeldTypPflichtBeschreibung
idnumberjaEreignis-Log-ID (Idempotenzschlüssel)
type_idstringjaEreignistyp-Kennung
user_idnumberjaHandelnder Benutzer (0 / 1 = System)
resource_idnumberneinZugehörige Ressourcen-ID
resource_namestringneinRessourcen- / Tabellenname
plant_node_idnumberneinZugehöriger Anlagenknoten
roasthubs_zone_idnumberneinZugehörige Zone
dataobjectneinEreignisspezifischer 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-ID
  • roasthubs_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: lots
  • resource_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-ID
  • roasthubs_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-ID
  • roasthubs_zone_id: Charge-Zone

data — Chargendatensatz einschließlich zugehöriger lots_targets.


Produktionen

production_create / production_update / production_delete

  • resource_id: Produktions-ID
  • roasthubs_zone_id: Produktionszone
  • plant_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: recipes
  • resource_id: Rezept-ID
  • roasthubs_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: recipes
  • resource_id: Komponenten-Rezept-ID, die ausgetauscht wird
  • roasthubs_zone_id: typischerweise 2

data — Request-Body des Massen-Austauschs (ausgewählte Rezepte, Austausch-Kaffee-ID, Benutzer-ID, …).


Verkauf

sale_create / sale_update

  • resource_name: sales
  • resource_id: Verkaufs-ID

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

sale_lines_create

  • resource_name: sales
  • resource_id: übergeordnete Verkaufs-ID

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

sale_lines_update

  • resource_name: sales oder sales_lines
  • resource_id: Verkaufs-ID oder Positions-ID (variiert je nach Aufrufer)

data — aktualisierter Verkaufspositionsdatensatz.


Produkte

product_create / product_update

  • resource_name: products
  • resource_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-ID
  • resource_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: contracts
  • resource_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_offs
  • resource_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_offs oder contracts_call_offs_lines
  • resource_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: sites
  • resource_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: targets
  • resource_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: returns
  • resource_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: containers
  • resource_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: containers
  • resource_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_lots
  • container_added_to_node
  • container_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: integrations
  • resource_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-Anlagenknoten
  • roasthubs_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-Anlagenknoten
  • roasthubs_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: typischerweise 2 (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: lots
  • resource_id: zugehörige Charge-ID

data — zugehöriger Chargendatensatz zum Validierungszeitpunkt.

Weitere geseedete Anlagensteuerungs-Ereignisse

Ereignis-IDBeschreibung
component_skipEine Dosierauftrags-Komponente überspringen
coponent_switchEine Dosierauftrags-Komponente wechseln
dumping_green_startEntladen gestartet
manual_control_runningAsset läuft (manuelle Steuerung)
manual_control_not_runningAsset läuft nicht (manuelle Steuerung)
manual_mode_onAsset auf manuellen Modus umgeschaltet
manual_mode_offAsset auf Automatikmodus umgeschaltet
production_plan_startProduktionsplan gestartet
production_plan_stopProduktionsplan gestoppt
switching_cell_dosing_orderZelle nach Flow-Alarm wechseln
tag_updateTag-Update
auto_cell_selectionAutomatische Zellenauswahl

System

user_comment

  • resource_name: z. B. contracts
  • resource_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_nodes
  • resource_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-IDBeschreibung
lot_createCharge anlegen
lot_updateCharge aktualisieren
lot_deleteCharge löschen

Außerdem ausgelöst: lot_target_pass, lot_target_fail, lot_qc_pass, lot_qc_fail.

Produktionen-Index

Ereignis-IDBeschreibung
production_createProduktion anlegen
production_updateProduktion aktualisieren
production_deleteProduktion löschen

Rezepte-Index

Ereignis-IDBeschreibung
recipe_createRezept anlegen
recipe_updateRezept aktualisieren
recipe_deleteRezept löschen
bulk_exchange_recipe_componentMassen-Austausch einer Rezeptkomponente

Verkauf-Index

Ereignis-IDBeschreibung
sale_createVerkauf anlegen
sale_updateVerkauf aktualisieren
sale_lines_createVerkaufsposition anlegen
sale_lines_updateVerkaufsposition aktualisieren

Produkte-Index

Ereignis-IDBeschreibung
product_createProdukt anlegen
product_updateProdukt aktualisieren
product_process_stage_createProdukt-Prozessstufe anlegen
product_process_stage_updateProdukt-Prozessstufe aktualisieren

Verträge- & Abrufe-Index

Ereignis-IDBeschreibung
contracts_createVertrag anlegen
contracts_updateVertrag aktualisieren
contracts_call_offs_createAbruf anlegen
contracts_call_offs_updateAbruf aktualisieren
contracts_call_offs_lines_createAbrufposition anlegen
contracts_call_offs_lines_updateAbrufposition aktualisieren
contracts_call_offs_lines_deleteAbrufposition löschen

Standorte-Index

Ereignis-IDBeschreibung
site_createStandort anlegen
site_updateStandort aktualisieren

Ziele-Index

Ereignis-IDBeschreibung
target_createZiel anlegen
target_updateZiel aktualisieren
target_deleteZiel löschen

Retouren-Index

Ereignis-IDBeschreibung
return_createRetoure anlegen
return_updateRetoure aktualisieren
return_add_lotCharge zur Retoure hinzufügen
return_remove_lotCharge aus Retoure entfernen

Behälter-Index

Ereignis-IDBeschreibung
container_creationBehälter anlegen (UI-ID; Code kann container_create auslösen)
container_updateBehälter aktualisieren
container_deletionBehälter löschen (UI-ID; Code kann container_delete auslösen)
container_remove_lotsChargen aus Behälter entfernen
container_added_to_nodeBehälter mit Anlagenknoten verknüpft
container_removed_from_nodeBehälter von Anlagenknoten getrennt

Außerdem ausgelöst: container_history_added.

Integrationen-Index

Ereignis-IDBeschreibung
integration_createIntegration anlegen
integration_updateIntegration aktualisieren
integration_deleteIntegration löschen

Anlagensteuerung-Index

Ereignis-IDBeschreibung
auto_cell_selectionAutomatische Zellenauswahl
cancel_dosing_orderGesamten Dosierauftrag abbrechen
cell_theoretical_weight_correctionTheoretische Zellengewichtskorrektur
component_skipDosierauftrags-Komponente überspringen
coponent_switchDosierauftrags-Komponente wechseln
dumping_green_startEntladen gestartet
dumping_green_lot_fully_finishedRohkaffee-Entladung; Charge vollständig entladen
dumping_green_lot_partially_finishedRohkaffee-Entladung; Charge teilweise entladen
lot_dump_fully_finishedEntladen gestoppt; Charge vollständig geleert
lot_dump_partially_finishedEntladen gestoppt; Charge teilweise geleert
inventory_cell_startZelleninventarisierung gestartet
inventory_cell_stopZelleninventarisierung gestoppt
manual_control_runningManuelle Steuerung läuft
manual_control_not_runningManuelle Steuerung läuft nicht
manual_mode_onManueller Modus ein
manual_mode_offAutomatikmodus ein
production_plan_startProduktionsplan gestartet
production_plan_stopProduktionsplan gestoppt
resolve_cell_not_foundFehlende Zellenkomponente auflösen
scale_validationWaagenvalidierung
skip_cell_dosing_orderZellen-Dosierauftrag überspringen
switching_cell_dosing_orderZelle für Dosierauftrag wechseln
tag_updateTag-Update

Außerdem ausgelöst: plant_node_update.

System-Index

Ereignis-IDBeschreibung
user_log_inBenutzer meldet sich an
user_log_outBenutzer meldet sich ab
user_commentBenutzerkommentar

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.