Webhooks

Ein Webhook ruft eine Adresse in Ihrem System auf, sobald bei einem Dokument ein bestimmtes Ereignis eintritt, z. B. wenn es abgeschlossen ist. Ihr System muss die Dokumenten-API dann nicht regelmäßig abfragen.

Webhooks gibt es für Bestellungen, Auftragsbestätigungen, Angebotsanfragen, Rechnungen und Lieferscheine.

Voraussetzungen

Ein Workbench-Konto mit der Rolle IT oder Admin (siehe Benutzer und Rollen).
Eine Adresse in Ihrem System, die aus dem Internet erreichbar ist und POST-Anfragen mit JSON annimmt. Verwenden Sie HTTPS.

Webhook einrichten

Klicken Sie in der linken Navigationsleiste auf Einstellungen und wählen Sie Integrationen.
Wählen Sie in der Unter-Navigation unter Workflow-Tools den Eintrag Webhooks.
Klicken Sie auf Webhook hinzufügen.
Füllen Sie die Felder aus (siehe Tabelle) und klicken Sie auf Webhook erstellen.

Feld	Bedeutung
Name	Name zur Unterscheidung in der Liste.
Aktiviert	Nur aktivierte Webhooks werden aufgerufen.
URL	Adresse Ihres Empfängers. Workist sendet `POST`-Anfragen mit JSON.
Auth-Typ	Präfix des Header-Werts, z. B. `Bearer`. Optional.
Auth-Zugangsdaten	Geheimer Wert für den Header, z. B. ein Token.
Auth-Header	Name des Headers. Standard: `Authorization`.
Benutzername	Benutzername für HTTP Basic Auth. Wenn gesetzt, gilt Basic Auth statt des Headers oben.
Passwort	Passwort für HTTP Basic Auth.
Ereignisse	Ereignisse, die den Webhook auslösen. Mindestens eines.
Unfertige Daten anzeigen	`data` enthält die Dokumentdaten auch vor dem Abschluss.
Kanäle	Kanäle je Dokumenttyp. Keine Auswahl: alle Kanäle aller Typen.

Die Liste zeigt alle Webhooks mit Status, URL und Anzahl der Ereignisse. Über das Stift-Symbol bearbeiten Sie einen Webhook, über das Papierkorb-Symbol löschen Sie ihn. Auth-Zugangsdaten und Passwort bleiben nach dem Speichern verborgen; lassen Sie die Felder beim Bearbeiten leer, bleibt der gespeicherte Wert erhalten.

Authentifizierung

Workist sendet bei jedem Aufruf genau einen Header zur Authentifizierung:

Basic Auth: Wenn Benutzername ausgefüllt ist, sendet Workist Authorization: Basic <Base64 von Benutzername:Passwort>.
Eigener Header: Sonst sendet Workist den Header aus Auth-Header (Standard Authorization) mit dem Wert <Auth-Typ> <Auth-Zugangsdaten>, z. B. Authorization: Bearer abc123. Ohne Auth-Typ steht nur der Wert aus Auth-Zugangsdaten im Header.

Workist signiert die Anfragen nicht. Prüfen Sie den Header in Ihrem System und nehmen Sie nur Anfragen über HTTPS an.

Kanäle

Ohne Auswahl gilt der Webhook für alle Kanäle aller Dokumenttypen.
Wählen Sie Kanäle aus, gilt der Webhook nur für diese Kanäle. Dokumenttypen, bei denen Sie keinen Kanal ausgewählt haben, lösen ihn dann nicht aus.

Ereignisse

Der Name eines Ereignisses setzt sich aus Dokumenttyp und Ereignis zusammen, z. B. order.finished oder invoice.assistance_needed.

Ereignis	Name	Bedeutung	Wird gesendet für
Unterstützung benötigt	`assistance_needed`	Das Dokument wartet auf Bearbeitung in der Workbench.	alle Dokumenttypen
Unterstützt	`assisted`	Ein Benutzer hat die Bearbeitung abgeschlossen oder das Dokument verworfen.	alle Dokumenttypen
Vor der Ausgabeerzeugung	`before_generate_output`	Workist beginnt, die Ausgabedatei zu erzeugen.	alle Dokumenttypen
Ausgabe erzeugt	`output_generated`	Die Ausgabedatei ist erzeugt.	alle Dokumenttypen
Vor dem Senden der Ausgabe	`before_send_output`	Workist beginnt mit der Übertragung.	Bestellungen, Angebotsanfragen
Ausgabe gesendet	`output_sent`	Die Übertragung ist abgeschlossen.	derzeit nie
Abgeschlossen	`finished`	Die Verarbeitung ist beendet: abgeschlossen, verworfen oder in einen anderen Kanal weitergeleitet.	alle Dokumenttypen

Dokumenttyp	Präfix
Bestellungen	`order.`
Auftragsbestätigungen	`order_confirmation.`
Angebotsanfragen	`rfq.`
Rechnungen	`invoice.`
Lieferscheine	`delivery_note.`

Hinweise:

Ausgabe gesendet wird derzeit nicht ausgelöst. Verwenden Sie Abgeschlossen und prüfen Sie data.status: DELIVERED heißt, Workist hat das Ergebnis per SFTP, AS2 oder ERP-Integration übertragen.
Abgeschlossen kommt auch für verworfene Dokumente (data.status ist dann DISCARDED). Schlägt die Übertragung fehl, sendet Workist kein Abgeschlossen.
Für die meisten Integrationen genügt Abgeschlossen. Unterstützung benötigt eignet sich, um Mitarbeitende auf offene Dokumente hinzuweisen.

Inhalt der Anfrage

Workist sendet eine POST-Anfrage mit Content-Type: application/json:

Feld	Inhalt
`timestamp`	Zeitpunkt des Ereignisses als Unix-Zeitstempel in Sekunden.
`event`	Name des Ereignisses, `<dokumenttyp>.<ereignis>`, z. B. `order.finished`.
`user`	Derzeit immer ein leeres Objekt.
`data`	Das Dokument im selben Format wie in der Dokumenten-API. Bei Rechnungen nur `{"id": ...}`.
`payload`	Für die auswählbaren Ereignisse immer ein leeres Objekt.

Beispiel (gekürzt):

{
  "timestamp": 1760000000,
  "event": "order.finished",
  "user": {},
  "data": {
    "id": "3f2a9c1e-7d1b-4c55-9a43-0e6f1b2c8d90",
    "channel": "8b1d2f40-5c3e-4a7a-9e21-6d4c3b2a1f00",
    "status": "FINISHED",
    "subject": "Bestellung 4500012345",
    "finished_at": "2026-10-09T08:15:42Z",
    "workbench_url": "https://wb.workist.com/...",
    "data": {
      "order_number": "4500012345",
      "line_items": []
    }
  },
  "payload": {}
}

data.data ist leer ({}), solange das Dokument weder bearbeitet noch abgeschlossen ist. Aktivieren Sie Unfertige Daten anzeigen, wenn Sie bei frühen Ereignissen schon die Zwischenstände brauchen.
Bei Rechnungen enthält data nur die ID. Rufen Sie die Rechnung mit GET /invoices/{id} über die Dokumenten-API ab.
Links zu Dateien in data sind höchstens 30 Minuten gültig.

Zustellung und Fehler

Workist sendet Webhooks im Hintergrund, kurz nach dem Ereignis. Die Reihenfolge mehrerer Ereignisse ist nicht garantiert. Ordnen Sie Ereignisse über timestamp und data.id zu.
Nicht erreichbar: Kommt keine Verbindung zustande, versucht Workist es bis zu zehnmal erneut, mit wachsendem Abstand von 1, 2, 4 bis 512 Sekunden (zusammen etwa 17 Minuten). Danach verwirft Workist das Ereignis.
Fehlerantwort: Antwortet Ihr System mit einem Fehlerstatus (4xx oder 5xx), wiederholt Workist den Aufruf nicht.
Die Workbench zeigt kein Protokoll der Aufrufe. Wenn Ihr System ein Ereignis verpasst hat, holen Sie die Dokumente über die Dokumenten-API ab, z. B. mit finished=true&imported=false.
Antworten Sie schnell mit einem 2xx-Status und verarbeiten Sie die Daten danach. Verarbeiten Sie Ereignisse so, dass ein doppelter Aufruf keinen Schaden anrichtet.

Voraussetzungen​

Webhook einrichten​

Authentifizierung​

Kanäle​

Ereignisse​

Inhalt der Anfrage​

Zustellung und Fehler​