Working with webhooks
A webhook is also known as an HTTP push or web callback. It is a way to provide a target application with new or updated data.
In ControlOffice, it is possible to configure a notification of the “webhook” type. In this case, a URL is specified for the notification. A notification can be configured via System Administration and then 'Configure notifications'.
How does it work?
ControlOffice can send notifications to a webhook.
The body of a webhook notification always has the same structure:
{ "subjectType": "<notification type name>", "subjectId": "<subject identifier>", "offsetType": "<offset type>", "offset": "<offset>", "tenant": "<tenant identifier>", "timestamp": "<timestamp, UTC>" } Properties
subjectType
Contains the type of the notification.
subjectId
Contains the ID of the subject to which the notification relates. This ID can be used in a GET request to the corresponding endpoint to retrieve the relevant record.
For example:
GET /api/v1/Request/1234-5678-9012-3456 offsetType
Contains the time unit of an optional offset. Possible values are None, Day, Week, Month and Year.
offset
Contains the number of days, weeks, months or years of the configured offset.
tenant
Contains the tenant identifier.
timestamp
Contains the time at which the notification was generated. The timestamp is displayed in UTC.
Requests
Endpoint: /api/v1/Request
| Notification Name Settings | Name | Settings |
|---|---|---|
| A new request has been created | RequestCreated |
|
| A request has been changed | RequestChanged |
|
| The status of a request has been changed | RequestStatusChanged |
|
| A request has been marked as ready | RequestMarkedReady |
|
| A workorder has been created from a request | WorkorderCreatedFromRequest |
Workorders
Endpoint: /api/v1/Workorder
| Notification Name Settings | Name | Settings |
|---|---|---|
| A new workorder has been created | WorkorderCreated |
|
| A workorder has been changed | WorkorderChanged |
|
| The status of a workorder has been changed | WorkorderStatusChanged |
|
| The responsible person on a workorder has been set | WorkorderResponsibleSet |
|
| The responsible person on a workorder has been removed or changed | WorkorderResponsibleRemoved |
|
| An employee has been added to a workorder | WorkorderEmployeeCreated |
|
| An employee has been removed from a workorder | WorkorderEmployeeRemoved |
|
| The planned date of a workorder is reached | WorkorderPlandateDue |
Number of days before the notification |
| A workorder has been marked as ready | WorkorderMarkedReady |
|
| A workorder has been marked as complete | WorkorderCompleted |
|
| A workorder has been closed | WorkorderClosed |
|
| The chat (memo field) of a workorder has been changed | WorkorderChatChanged |
Purchasing
Endpoint: /api/v1/PurchaseOrder
| Notification Name Settings | Name | Settings |
|---|---|---|
| A new purchase order has been created | PurchaseOrderCreated |
|
| A purchase order has been changed | PurchaseOrderChanged |
|
| The status of a purchase order has been changed | PurchaseOrderStatusChanged |
|
| A purchase order may be ordered | PurchaseOrderSendToSupplier |
|
| A purchase order has been ordered | PurchaseOrderSentToSupplier |
|
| A purchase order has had a delivery | PurchaseOrderFirstDelivery |
|
| A purchase order has been marked as complete | PurchageOrderFinalDelivery |
|
| The delivery date of a purchase order has passed | PurchaseOrderDeliveryDateDue |
Purchase advice
Endpoint: /api/v1/PartStock
| Notification Name Settings | Name | Settings |
|---|---|---|
| A part in a warehouse reaches the minimum stock level | PartStockMinimalStock |
Issue
Endpoint: /api/v1/GoodsMovement
| Notification Name Settings | Name | Settings |
|---|---|---|
| A part has been issued | PartIssue |
Planning lines
| Notification Name Settings | Name | Settings |
|---|---|---|
| A planning line turns orange | PlanningLineInPlanzone |
|
| A planning line turns red | PlanningLineAfterPlanzone |
Contracts
Endpoint: /api/v1/Contract
| Notification Name Settings | Name | Settings |
|---|---|---|
| The warning date of a contract has passed | ContractEndDateDue |
Offset relative to the planned date of a workorder For the WorkorderPlanDateDue notification, the notification settings are also included.
For this type of notification, you can configure how much time before or after the planned date the notification should be sent.
An example is a notification that is sent three days before the planned date of a workorder.
The offsetType property determines the time unit used:
NoneDayWeekMonthYear
The offset property contains the corresponding number of days, weeks, months or years.
Tenant
The tenant property contains the tenant identifier. By default, this identifier is only used by ControlOffice itself.
When an external provider processes webhooks for multiple ControlOffice tenants, the tenant identifier can be used to implement a multitenant solution.
Timestamp
The timestamp property contains the time at which the notification was generated by ControlOffice.
The timestamp is displayed in UTC.
Security
Webhook calls can include additional HTTP headers. These headers can be configured in ControlOffice.
Additional query parameters can also be added to the webhook URL. These can be used, for example, to include authentication details or other data required by the receiving application.