# 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](/docs/api-documentation/document-api.md) dann nicht regelmäßig abfragen. Webhooks gibt es für Bestellungen, Auftragsbestätigungen, Angebotsanfragen, Rechnungen und Lieferscheine. ## Voraussetzungen {#voraussetzungen} - Ein Workbench-Konto mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). - Eine Adresse in Ihrem System, die aus dem Internet erreichbar ist und `POST`-Anfragen mit JSON annimmt. Verwenden Sie HTTPS. ## Webhook einrichten {#einrichten} 1. Klicken Sie in der linken Navigationsleiste auf **Einstellungen** und wählen Sie **Integrationen**. 2. Wählen Sie in der Unter-Navigation unter **Workflow-Tools** den Eintrag **Webhooks**. 3. Klicken Sie auf **Webhook hinzufügen**. 4. 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 {#authentifizierung} Workist sendet bei jedem Aufruf genau einen Header zur Authentifizierung: - **Basic Auth:** Wenn **Benutzername** ausgefüllt ist, sendet Workist `Authorization: Basic `. - **Eigener Header:** Sonst sendet Workist den Header aus **Auth-Header** (Standard `Authorization`) mit dem Wert ` `, 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 {#kanaele} - 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 {#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 {#inhalt} 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, `.`, z. B. `order.finished`. | | `user` | Derzeit immer ein leeres Objekt. | | `data` | Das Dokument im selben Format wie in der [Dokumenten-API](/docs/api-documentation/document-api.md). Bei Rechnungen nur `{"id": ...}`. | | `payload` | Für die auswählbaren Ereignisse immer ein leeres Objekt. | Beispiel (gekürzt): ```json { "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](/docs/api-documentation/document-api.md) ab. - Links zu Dateien in `data` sind höchstens 30 Minuten gültig. ## Zustellung und Fehler {#zustellung} - 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](/docs/api-documentation/document-api.md#ablauf) 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.