Webhooks

Webhooks

Webhooks ermöglichen es Ihrem Board, HTTP-Anfragen an externe Dienste zu senden, wann immer bestimmte Ereignisse während der Produktion eintreten — eine Menge wird erfasst, eine Aufgabe wird gestartet, eine Aufgabe wird blockiert, ein Auftrag wird abgeschlossen und mehr. So verbinden Sie Ihr Board mit Slack, Microsoft Teams, einem ERP, einer Benachrichtigungsplattform, einem eigenen Skript oder allem anderen, was eine HTTP-Anfrage empfangen kann.

Webhooks finden Sie unter App-Einstellungen → Webhooks.

Hinweis: Webhooks müssen für Ihr Konto aktiviert sein. Wenn die Seite einen Hinweis zeigt, dass Webhooks deaktiviert sind, wenden Sie sich an den Support, um sie einschalten zu lassen.

---

Inhaltsverzeichnis

1. Was ist ein Webhook?
2. Wann Webhooks zu verwenden sind
3. Einen Webhook erstellen
4. Feldreferenz
5. Ereignisse, die Sie abonnieren können
6. Payload-Referenz
7. Authentifizierung (API-Schlüssel)
8. Arbeitsplatz-Eingrenzung
9. Einen Webhook testen
10. Anwendungsbeispiele
11. Protokolle und Fehlerbehebung
12. Sicherheitshinweise

---

Was ist ein Webhook?

Ein Webhook ist eine URL, die Sie Ihrem Board mitteilen. Wann immer ein Ereignis eintritt, das Sie abonniert haben, sendet das Board eine HTTP-POST-Anfrage an diese URL mit einer kleinen JSON-Payload, die beschreibt, was passiert ist.

Das andere Ende ist Ihre Wahl — eine Slack-Incoming-Webhook-URL, ein Zapier-„Catch Hook”-Trigger, ein Endpunkt auf Ihrem eigenen Server, eine Automatisierungsplattform, alles, was HTTP empfangen und JSON parsen kann.

Webhooks sind einseitig und fire-and-forget — das Board wartet nicht auf eine sinnvolle Antwort, es protokolliert nur den Statuscode für die Diagnose. Wenn Ihr Endpunkt langsam oder vorübergehend nicht erreichbar ist, wiederholt das Board nicht automatisch.

---

Wann Webhooks zu verwenden sind

Einige reale Anwendungsfälle:

• Benachrichtigungen — posten Sie eine Nachricht in Slack/Teams, wann immer eine Aufgabe blockiert wird, ein Auftrag abgeschlossen wird oder eine Aufgabe mit hoher Priorität an einem bestimmten Arbeitsplatz beginnt.
• ERP / Buchhaltungs-Synchronisation — lassen Sie Ihr Backoffice-System wissen, dass Mengen gefertigt wurden, damit Inventar und Rechnungsstellung aktualisiert werden können.
• Benutzerdefinierte Dashboards — speisen Sie ein externes Grafana, Looker oder selbstgebautes Dashboard mit Produktionsdaten in Echtzeit.
• Auslösen anderer Automatisierungen — starten Sie den Druck von Versandetiketten, Verpackungsanweisungen oder Qualitätskontroll-Workflows, wenn ein Auftrag einen abgeschlossenen Status erreicht.
• Audit- / Compliance-Protokollierung — streamen Sie jede Mengenänderung oder jedes Zeitprotokoll in ein externes Archiv.

---

Einen Webhook erstellen

1. Gehen Sie zu App-Einstellungen → Webhooks.
2. Füllen Sie das Formular oben auf der Seite aus:
   • Quelle — welche Bestellquelle diesen Webhook auslösen soll (oder Alle Quellen).
   • Webhook-URL — die URL, die Ihr externer Dienst bereitstellt.
   • API-Schlüssel (optional) — ein Authentifizierungstoken (siehe Authentifizierung).
   • Ereignisse — kreuzen Sie ein oder mehrere Ereignisse an, die Sie empfangen möchten.
   • Arbeitsplätze (optional) — wählen Sie bestimmte Arbeitsplätze zum Eingrenzen oder lassen Sie leer, um für alle Arbeitsplätze auszulösen.
3. Klicken Sie auf Hinzufügen (oder Aktualisieren beim Bearbeiten eines bestehenden Webhooks).

Der neue Webhook erscheint in der Tabelle darunter. Sie können ihn jederzeit bearbeiten, löschen oder eine manuelle Testanfrage senden.

---

Feldreferenz

Feld	Beschreibung
Quelle	Die Bestellquelle, für die der Webhook gilt. Wählen Sie Alle Quellen, um Ereignisse für Bestellungen aus jeder Quelle zu empfangen, oder wählen Sie einen bestimmten Quellschlüssel (manual, shopify usw.), um nur auszulösen, wenn die Bestellung des Auftrags aus dieser Quelle stammt.
Webhook-URL	Die vollständige HTTPS-URL, an die das Board POSTen soll. Maximal 2000 Zeichen.
API-Schlüssel (optional)	Wenn gesetzt, sendet das Board ihn bei jeder Anfrage in zwei Headern — Authorization: Bearer <key> und X-API-Key: <key>. Verwenden Sie dies, wenn Ihr Endpunkt Authentifizierung erfordert. Leer lassen für öffentliche Endpunkte (z. B. Slack-Incoming-Webhooks).
Ereignisse	Ein oder mehrere Ereignisse, die diesen Webhook auslösen. Siehe Ereignisse.
Arbeitsplätze (optional)	Eine Liste von Arbeitsplätzen, auf die dieser Webhook beschränkt ist. Leer = für alle Arbeitsplätze auslösen. Siehe Arbeitsplatz-Eingrenzung.

---

Ereignisse, die Sie abonnieren können

Jeder Webhook löst nur für Ereignisse aus, die Sie angekreuzt haben. Sie können beliebig viele ankreuzen.

qty_changed — Menge geändert

Wird jedes Mal ausgelöst, wenn eine Menge gegen einen Arbeitsplatz auf einem Auftrag erfasst wird — über das Dashboard, den Kiosk, die Mobile App oder die API. Die Payload enthält den Arbeitsplatz, die bisher insgesamt gefertigte Menge für den Auftrag und identifizierende Felder über Auftrag und Bestellung.

Beispielverwendung: ein ERP-System in Echtzeit mit Fertigungsfortschritt speisen.

time_log_saved — Zeitprotokoll gespeichert

Wird ausgelöst, wann immer ein Zeiterfassungsprotokolleintrag erstellt wird — entweder manuell über die Kiosk-Schaltfläche „Senden” oder wenn ein Timer gestoppt wird. Die Payload enthält die Dauer in Minuten, den Mitarbeiter, den Arbeitsplatz, jede Notiz und die Menge (falls vorhanden), die gleichzeitig protokolliert wurde.

Beispielverwendung: Produktivität in ein Abrechnungs-/Lohnabrechnungssystem protokollieren.

job_blocked — Aufgabe blockiert

Wird ausgelöst, wenn ein Mitarbeiter eine Aufgabe als blockiert markiert (z. B. „fehlendes Material”, „Maschine ausgefallen”). Die Payload enthält die Blockierungsnotiz, die den Grund erklärt.

Beispielverwendung: einen sofortigen Alarm an Slack senden, damit ein Schichtleiter untersuchen kann.

job_completed — Aufgabe abgeschlossen (ganzer Auftrag)

Wird ausgelöst, wenn ein gesamter Auftrag abgeschlossen ist — d. h. wenn der Status des Auftrags in den konfigurierten Abschlussstatus übergeht (entweder manuell geändert oder automatisch, wenn jeder Arbeitsplatz seine geplante Menge erreicht). Die Payload enthält die Gesamtdauer in Minuten über alle Zeiterfassungseinträge des Auftrags.

Beispielverwendung: einen Versandetiketten- oder Rechnungsstellungs-Workflow auslösen, sobald ein Auftrag vollständig erledigt ist.

task_started — Aufgabe am Arbeitsplatz gestartet

Wird einmal pro Arbeitsplatz pro Auftrag ausgelöst, beim ersten Mal, dass Aktivität darauf erfasst wird. Aktivität bedeutet entweder, dass die erste Menge > 0 protokolliert wird, oder dass der erste Zeiterfassungs-Timer an diesem Arbeitsplatz gestartet wird — was zuerst kommt. Die Payload enthält einen ISO-Zeitstempel started_at.

Beispielverwendung: einen Schichtleiter benachrichtigen, dass die Arbeit an einem kritischen Schritt begonnen hat, damit er weiß, dass die Produktion tatsächlich gestartet ist.

task_completed — Aufgabe am Arbeitsplatz abgeschlossen

Wird einmal pro Arbeitsplatz pro Auftrag ausgelöst, beim ersten Mal, dass dieser Arbeitsplatz seine geplante Menge erreicht (oder bei Abteilungen mit geteilter Menge, in dem Moment, in dem die gepoolte Abteilungsmenge die Gesamtmenge des Auftrags erfüllt). Die Payload enthält einen ISO-Zeitstempel completed_at.

Beispielverwendung: das nachgelagerte System des nächsten Schritts (Verpackung, QS, Versand) in dem Moment auslösen, in dem eine bestimmte Produktionsstufe endet.

Idempotenz für task_started / task_completed: jedes wird dauerhaft auf der Arbeitsplatzzeile aufgezeichnet, sodass es nur beim ersten Mal ausgelöst wird, wenn die Bedingung erfüllt ist. Das Protokollieren weiterer Mengen oder das Neustarten eines Timers nach dem ersten Treffer wird diese Ereignisse nicht erneut auslösen.

---

Payload-Referenz

Jedes Ereignis sendet ein JSON-Objekt per HTTP-POST. Einige Felder sind für alle Ereignisse gemeinsam; andere sind spezifisch für den Ereignistyp. Leere/null-Felder werden weggelassen, um die Payloads kompakt zu halten.

Basisfelder (in allen Ereignissen vorhanden)

{
    "event": "qty_changed",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "order_external_id": "EXT-12345",
    "manufactured_qty": 7,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "external_id": "ORD-7890",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12
}

Feld	Bedeutung
event	Der Ereignisschlüssel — eines der sechs oben aufgeführten.
job_ref	Die Referenznummer des Auftrags auf Ihrem Board.
order_ref	Die Referenz der übergeordneten Bestellung, falls vorhanden.
order_external_id	Die externe ID der Bestellung (z. B. eine Shopify-Bestell-ID).
manufactured_qty	Insgesamt gefertigte Menge für diesen Auftrag über alle Arbeitsplätze. (Für time_log_saved ist dies die Gesamtmenge des Arbeitsplatzes, nicht die des Auftrags.)
sku	Die SKU des Auftrags.
name	Der Name des Auftrags.
external_id	Die externe ID des Auftrags (z. B. der Bezeichner des vorgelagerten Systems).
department	Abteilung des beteiligten Arbeitsplatzes, falls ein Arbeitsplatz im Kontext ist.
workstation	Name des beteiligten Arbeitsplatzes.
workstation_id	Numerische ID des beteiligten Arbeitsplatzes.

Die Felder department, workstation und workstation_id sind vorhanden, wann immer sich das Ereignis auf einen bestimmten Arbeitsplatz bezieht (also alle Ereignisse außer job_completed, das den gesamten Auftrag betrifft).

Pro-Ereignis-Extras

Ereignis	Zusätzliche Felder
qty_changed	—
time_log_saved	mode ("manual" oder "work_stopped"), log_qty, log_note, duration_minutes, employee (Objekt mit id, name, surname)
job_blocked	block_note
job_completed	status (Name des Abschlussstatus), total_duration_minutes
task_started	started_at (ISO 8601-Zeitstempel)
task_completed	completed_at (ISO 8601-Zeitstempel)

Beispiel: task_started-Payload

{
    "event": "task_started",
    "job_ref": "PB-0042",
    "order_ref": "PO-2025-001",
    "manufactured_qty": 0,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "started_at": "2026-05-27T08:14:32+00:00"
}

Beispiel: time_log_saved-Payload

{
    "event": "time_log_saved",
    "job_ref": "PB-0042",
    "manufactured_qty": 5,
    "sku": "TABLE-OAK-90",
    "name": "Oak Coffee Table",
    "department": "Assembly",
    "workstation": "Station A",
    "workstation_id": 12,
    "mode": "work_stopped",
    "log_qty": 2,
    "log_note": "Two units finished, third in progress",
    "duration_minutes": 47,
    "employee": { "id": 8, "name": "Jan", "surname": "Kowalski" }
}

---

Authentifizierung (API-Schlüssel)

Wenn Ihr Endpunkt Authentifizierung erfordert, füllen Sie das Feld API-Schlüssel aus. Das Board sendet ihn bei jeder Anfrage in zwei Headern:

Authorization: Bearer <your-api-key>
X-API-Key: <your-api-key>

Die meisten Endpunkte akzeptieren eine der beiden Formen, sodass es egal ist, welche Sie auf der Empfangsseite prüfen.

Lassen Sie API-Schlüssel leer für öffentliche Endpunkte wie Slack-Incoming-Webhooks — sie erwarten keinen Authentifizierungs-Header.

---

Arbeitsplatz-Eingrenzung

Standardmäßig löst ein Webhook für jeden Arbeitsplatz aus. Das optionale Feld Arbeitsplätze lässt Sie ihn einschränken.

Leere Liste (Standard)

Der Webhook löst für alle Arbeitsplätze aus. Dies ist das ursprüngliche Verhalten — bestehende Webhooks, die vor dieser Funktion erstellt wurden, sind nicht betroffen.

Bestimmte Arbeitsplätze

Der Webhook löst nur aus, wenn der Arbeitsplatz des Ereignisses in der Liste ist. Nützlich, wenn:

• Sie möchten, dass ein Slack-Kanal nur Alarme für die Arbeitsplätze des Lackierteams empfängt.
• Sie eine ERP-Integration möchten, die sich nur für Endmontage-Arbeitsplätze interessiert.
• Verschiedene Teams unterschiedliche Benachrichtigungen empfangen sollen.

Verhalten bei Nicht-Arbeitsplatz-Ereignissen

Das Ereignis job_completed wird auf der ganzen Auftragsebene ausgelöst (kein bestimmter Arbeitsplatz). Ein Webhook mit einem oder mehreren ausgewählten Arbeitsplätzen wird für job_completed nicht ausgelöst — beabsichtigt. Wenn Sie möchten, dass ein Webhook job_completed empfängt, lassen Sie die Arbeitsplatzliste leer (oder erstellen Sie einen zweiten Webhook nur für dieses Ereignis).

Kombiniert mit Quelle

Der Arbeitsplatzfilter wird zusätzlich zum Quellfilter angewendet. Ein Webhook mit source=shopify und Arbeitsplätzen [A, B] löst nur aus, wenn das Ereignis beidem entspricht — ein Shopify-Quell-Auftragsereignis, das an Arbeitsplatz A oder B passiert.

---

Einen Webhook testen

Die Webhook-Tabelle hat ein Papierflieger-Symbol (✈) neben jeder Zeile — klicken Sie darauf, um den Testdialog zu öffnen.

1. Wählen Sie ein Ereignis aus den abonnierten Ereignissen Ihres Webhooks.
2. Eine Beispiel-Payload wird als JSON gerendert. Bearbeiten Sie sie frei — ändern Sie jedes Feld, um ein reales Szenario zu simulieren.
3. Klicken Sie auf Test senden. Der Dialog wechselt zu einem Ergebnisbereich, der zeigt:
   • HTTP-Statuscode, der von Ihrem Endpunkt zurückgegeben wurde
   • Benötigte Zeit (in Millisekunden)
   • Antwortkörper (auf 2 KB gekürzt)
   • Etwaige Verbindungsfehler
4. Klicken Sie auf Zurück zu Bearbeiten, um die Payload anzupassen und erneut zu versuchen.

Dies ist der schnellste Weg zu verifizieren, dass Ihr Endpunkt erreichbar ist, die Payload korrekt parst und mit einem 2xx-Status antwortet.

---

Anwendungsbeispiele

1. Slack-Alarm, wenn eine Aufgabe blockiert wird

• Quelle: Alle Quellen
• URL: eine Slack Incoming-Webhook-URL
• API-Schlüssel: leer
• Ereignisse: nur job_blocked
• Arbeitsplätze: leer

In Slack kommt die Payload als JSON an; Sie können sie mit einem Relay schön formatieren (z. B. einem Cloudflare Worker, der block_note + workstation in eine Slack-Nachricht verwandelt). Oder verwenden Sie einen Dienst wie Zapier zwischen den beiden, um die Formatierung zu übernehmen.

2. E-Mail an einen Schichtleiter, wenn die Lackiererei einen Auftrag fertigstellt

• Quelle: Alle Quellen
• URL: eine Zapier-„Catch Hook”-URL, verbunden mit einem Gmail-„E-Mail senden”-Schritt
• Ereignisse: task_completed
• Arbeitsplätze: alle Lackier-Arbeitsplätze ankreuzen

Der Webhook löst in dem Moment aus, in dem der Lackier-Anteil eines Auftrags erledigt ist. Zapier formatiert die E-Mail aus den Payload-Feldern.

3. Gefertigte Mengen an ein ERP senden

• Quelle: eine bestimmte externe Quelle (z. B. shopify)
• URL: der Eingangs-Endpunkt Ihres ERPs
• API-Schlüssel: das API-Token des ERPs
• Ereignisse: qty_changed, job_completed
• Arbeitsplätze: leer (Sie möchten alle)

Das ERP erhält eine Payload nach jeder Mengenänderung plus eine abschließende Ganzes-Auftrag-Benachrichtigung, wenn der Auftrag vollständig fertig ist.

4. Verschiedene Benachrichtigungen pro Abteilung

Erstellen Sie drei separate Webhooks, jeweils auf die Arbeitsplätze ihrer eigenen Abteilung beschränkt:

• „Montage Slack” → task_started, task_completed, job_blocked, Arbeitsplätze = nur Montagestationen
• „Lackier Slack” → gleiche Ereignisse, Arbeitsplätze = nur Lackier-Stationen
• „Verpackung Slack” → gleiche Ereignisse, Arbeitsplätze = nur Verpackungs-Stationen

Jedes Team sieht nur Alarme, die für sie relevant sind.

---

Protokolle und Fehlerbehebung

Jede Webhook-Anfrage — sowohl echte Ereignisse als auch manuelle Tests — wird an ein pro-Mandant-Protokoll auf dem Server angehängt unter:

storage/logs/webhooks/webhook_tennent_id_<tenant_id>.log

Jede Zeile ist ein JSON-Objekt mit Zeitstempel, Ereignis, URL, HTTP-Status, Dauer, Payload, Antwortkörper und etwaigen Fehlern. Dies ist die erste Stelle, an der Sie nachsehen sollten, wenn ein Webhook anscheinend nicht zugestellt wird.

Häufige Probleme

• Endpunkt gibt 4xx / 5xx zurück — prüfen Sie den Antwortkörper im Protokoll. Das Board hört erst beim nächsten Ereignis auf zu senden, wenn die URL entfernt wird; es versucht das aktuelle Ereignis nicht automatisch erneut.
• Keine Protokollzeile für ein Ereignis — Ihr Webhook trifft nicht zu. Überprüfen Sie die Filter Quelle, Ereignisse und Arbeitsplätze. Der Test-Dialog umgeht diese Filter und ist der schnellste Weg zu bestätigen, dass die URL funktioniert.
• Langsamer Endpunkt — der Anfrage-Timeout des Boards beträgt 10 Sekunden. Wenn Ihr Endpunkt länger braucht, bricht die Verbindung ab und ein Fehler wird protokolliert.
• HTTPS-Fehler — stellen Sie sicher, dass Ihr Endpunkt ein gültiges Zertifikat hat. Das Board erlaubt keine selbst signierten Zertifikate.
• Mandanten-Flag deaktiviert — die Seite zeigt einen Deaktivierungs-Hinweis, wenn Webhooks für Ihr Konto ausgeschaltet sind. Kontaktieren Sie den Support.

---

Sicherheitshinweise

• Die URL selbst ist die Berechtigung, wenn kein API-Schlüssel gesetzt ist. Jeder, der die URL eines nicht authentifizierten Webhooks kennt (z. B. einen Slack-Incoming-Webhook), kann an ihn posten. Behandeln Sie nicht authentifizierte URLs als Geheimnisse und teilen Sie sie nicht öffentlich.
• Verwenden Sie das API-Schlüssel-Feld, wann immer Ihr Endpunkt Auth unterstützt. Es ist ein kostenloses Sicherheits-Upgrade — das Board sendet ihn mit jeder Anfrage.
• HTTPS ist erforderlich für jeden Endpunkt, der echte Produktionsdaten verarbeitet. Das Webhook-URL-Feld akzeptiert auch http://, aber verwenden Sie es nur für lokale Entwicklung.
• Payloads enthalten identifizierbare Bestellungs-/Kundeninformationen. Stellen Sie sicher, dass der empfangende Dienst für die Verarbeitung dieser Daten freigegeben ist — insbesondere für externe Quellen, Drittanbieter-Automatisierungsplattformen und jeden Dienst, der die Payloads speichert oder protokolliert.
• Webhooks sind pro Mandant. Ereignisse aus den Daten eines Mandanten können niemals die Webhooks eines anderen Mandanten erreichen.