Arbeiten mit Webhooks
Ein Webhook wird auch als HTTP-Push oder Web-Callback bezeichnet. Er ist eine Möglichkeit, eine Zielanwendung mit neuen oder geänderten Daten zu versorgen.
In ControlOffice ist es möglich, eine Benachrichtigung vom Typ „Webhook“ einzurichten. In diesem Fall wird für die Benachrichtigung eine URL angegeben. Eine Benachrichtigung kann über die Systemverwaltung und anschließend über 'Benachrichtigungen konfigurieren' eingerichtet werden.
Wie funktioniert es?
ControlOffice kann Benachrichtigungen an einen Webhook senden.
Der Body einer Webhook-Benachrichtigung hat immer dieselbe Struktur:
{ "subjectType": "<Name des Benachrichtigungstyps>", "subjectId": "<Identifikation des Subjects>", "offsetType": "<Offset-Typ>", "offset": "<Offset>", "tenant": "<Identifikation des Tenants>", "timestamp": "<Zeitstempel, UTC>" } Properties
subjectType
Enthält den Typ der Benachrichtigung.
subjectId
Enthält die ID des Subjects, auf das sich die Benachrichtigung bezieht. Mit dieser ID kann über einen GET-Request an den entsprechenden Endpoint der betreffende Datensatz abgerufen werden.
Zum Beispiel:
GET /api/v1/Request/1234-5678-9012-3456 offsetType
Enthält die Zeiteinheit eines eventuellen Offsets. Mögliche Werte sind None, Day, Week, Month und Year.
offset
Enthält die Anzahl der Tage, Wochen, Monate oder Jahre des eingestellten Offsets.
tenant
Enthält die Identifikation des Tenants.
timestamp
Enthält den Zeitpunkt, zu dem die Benachrichtigung generiert wurde. Der Zeitstempel wird in UTC angegeben.
Meldungen
Endpoint: /api/v1/Request
| Benachrichtigung Name Einstellungen | ||
|---|---|---|
| Eine neue Meldung wurde erstellt | RequestCreated |
|
| Eine Meldung wurde geändert | RequestChanged |
|
| Der Status einer Meldung wurde geändert | RequestStatusChanged |
|
| Eine Meldung wurde fertiggemeldet | RequestMarkedReady |
|
| Aus einer Meldung wurde ein Arbeitsauftrag erstellt | WorkorderCreatedFromRequest |
Arbeitsaufträge
Endpoint: /api/v1/Workorder
| Benachrichtigung Name Einstellungen | ||
|---|---|---|
| Ein neuer Arbeitsauftrag wurde erstellt | WorkorderCreated |
|
| Ein Arbeitsauftrag wurde geändert | WorkorderChanged |
|
| Der Status eines Arbeitsauftrags wurde geändert | WorkorderStatusChanged |
|
| Der Verantwortliche eines Arbeitsauftrags wurde festgelegt | WorkorderResponsibleSet |
|
| Der Verantwortliche eines Arbeitsauftrags wurde entfernt oder geändert | WorkorderResponsibleRemoved |
|
| Ein Mitarbeiter wurde einem Arbeitsauftrag hinzugefügt | WorkorderEmployeeCreated |
|
| Ein Mitarbeiter wurde aus einem Arbeitsauftrag entfernt | WorkorderEmployeeRemoved |
|
| Das Planungsdatum eines Arbeitsauftrags wird erreicht | WorkorderPlandateDue |
Anzahl Tage vor der Benachrichtigung |
| Ein Arbeitsauftrag wurde fertiggemeldet | WorkorderMarkedReady |
|
| Ein Arbeitsauftrag wurde als vollständig gemeldet | WorkorderCompleted |
|
| Ein Arbeitsauftrag wurde abgeschlossen | WorkorderClosed |
|
| Der Chat (das Memofeld) eines Arbeitsauftrags wurde geändert | WorkorderChatChanged |
Einkauf
Endpoint: /api/v1/PurchaseOrder
| Benachrichtigung Name Einstellungen | ||
|---|---|---|
| Eine neue Bestellung wurde erstellt | PurchaseOrderCreated |
|
| Eine Bestellung wurde geändert | PurchaseOrderChanged |
|
| Der Status einer Bestellung wurde geändert | PurchaseOrderStatusChanged |
|
| Eine Bestellung darf bestellt werden | PurchaseOrderSendToSupplier |
|
| Eine Bestellung wurde bestellt | PurchaseOrderSentToSupplier |
|
| Es gab eine Lieferung für eine Bestellung | PurchaseOrderFirstDelivery |
|
| Eine Bestellung wurde als vollständig gemeldet | PurchageOrderFinalDelivery |
|
| Das Lieferdatum einer Bestellung wurde überschritten | PurchaseOrderDeliveryDateDue |
Bestellvorschlag
Endpoint: /api/v1/PartStock
| Benachrichtigung Name Einstellungen | ||
|---|---|---|
| Ein Teil in einem Lager erreicht den Mindestbestand | PartStockMinimalStock |
Ausgabe
Endpoint: /api/v1/GoodsMovement
| Benachrichtigung Name Einstellungen | ||
|---|---|---|
| Ein Teil wurde ausgegeben | PartIssue |
Planungszeilen
| Benachrichtigung Name Einstellungen | ||
|---|---|---|
| Eine Planungszeile wird orange | PlanningLineInPlanzone |
|
| Eine Planungszeile wird rot | PlanningLineAfterPlanzone |
Verträge
Endpoint: /api/v1/Contract
| Benachrichtigung Name Einstellungen | ||
|---|---|---|
| Das Warndatum eines Vertrags wurde überschritten | ContractEndDateDue |
Offset beim Planungsdatum eines Arbeitsauftrags Bei der Benachrichtigung WorkorderPlanDateDue werden auch die Einstellungen der Benachrichtigung mitgesendet.
Für diesen Benachrichtigungstyp kann eingestellt werden, wie viel Zeit vor oder nach dem Planungsdatum die Benachrichtigung gesendet werden soll.
Ein Beispiel ist eine Benachrichtigung, die drei Tage vor dem geplanten Datum eines Arbeitsauftrags gesendet wird.
Die Property offsetType bestimmt die verwendete Zeiteinheit:
NoneDayWeekMonthYear
Die Property offset enthält die entsprechende Anzahl an Tagen, Wochen, Monaten oder Jahren.
Tenant
Die Property tenant enthält die Identifikation des Tenants. Diese Identifikation wird grundsätzlich nur von ControlOffice selbst verwendet.
Wenn ein externer Anbieter Webhooks für mehrere ControlOffice-Tenants verarbeitet, kann die Tenant-Identifikation verwendet werden, um eine Multitenant-Lösung zu realisieren.
Timestamp
Die Property timestamp enthält den Zeitpunkt, zu dem die Benachrichtigung von ControlOffice generiert wurde.
Der Zeitstempel wird in UTC angegeben.
Sicherheit
Webhook-Aufrufe können mit zusätzlichen HTTP-Headern versehen werden. Diese Header können in ControlOffice konfiguriert werden.
Zusätzlich können weitere Query-Parameter zur Webhook-URL hinzugefügt werden. Damit können beispielsweise Authentifizierungsdaten oder andere Daten mitgesendet werden, die für die empfangende Anwendung erforderlich sind.