Werken met webhooks

In ControlOffice is het mogelijk een notificatie van het type “webhook” op te zetten. In dat geval wordt een URL bij de notificatie opgegeven. Een notificatie is in te stellen via systeembeheer en dan 'Instellen notificaties'.

Hoe werkt het?

ControlOffice kan notificaties versturen naar een webhook.

De body van een webhooknotificatie heeft altijd dezelfde structuur:

{   "subjectType": "<naam notificatie-type>",   "subjectId": "<identificatie van subject>",   "offsetType": "<type offset>",   "offset": "<offset>",   "tenant": "<identificatie van de tenant>",   "timestamp": "<timestamp, UTC>" }

Properties

subjectType
Bevat het type van de notificatie.

subjectId
Bevat het ID van het onderwerp waarop de notificatie betrekking heeft. Met dit ID kan via een GET-request naar het bijbehorende endpoint het betreffende record worden opgehaald.

Bijvoorbeeld:

GET /api/v1/Request/1234-5678-9012-3456

offsetType
Bevat de tijdeenheid van een eventuele offset. Mogelijke waarden zijn None, Day, Week, Month en Year.

offset
Bevat het aantal dagen, weken, maanden of jaren van de ingestelde offset.

tenant
Bevat de identificatie van de tenant.

timestamp
Bevat het tijdstip waarop de notificatie is gegenereerd. De timestamp wordt weergegeven in UTC.

Meldingen

Endpoint: /api/v1/Request

Notificatie	Naam
Een nieuwe melding is gemaakt	`RequestCreated`
Een melding is gewijzigd	`RequestChanged`
De status van een melding is gewijzigd	`RequestStatusChanged`
Een melding is gereed gemeld	`RequestMarkedReady`
Er is een werkorder gemaakt van een melding	`WorkorderCreatedFromRequest`

Werkorders

Endpoint: /api/v1/Workorder

Notificatie	Naam	Instellingen
Een nieuwe werkorder is gemaakt	`WorkorderCreated`
Een werkorder is gewijzigd	`WorkorderChanged`
De status van een werkorder is gewijzigd	`WorkorderStatusChanged`
De verantwoordelijke op een werkorder is ingesteld	`WorkorderResponsibleSet`
De verantwoordelijke op een werkorder is verwijderd of gewijzigd	`WorkorderResponsibleRemoved`
Een medewerker is toegevoegd aan een werkorder	`WorkorderEmployeeCreated`
Een medewerker is verwijderd van een werkorder	`WorkorderEmployeeRemoved`
De plandatum van een werkorder wordt bereikt	`WorkorderPlandateDue`	Aantal dagen voor de notificatie
Een werkorder is gereed gemeld	`WorkorderMarkedReady`
Een werkorder is compleet gemeld	`WorkorderCompleted`
Een werkorder is afgesloten	`WorkorderClosed`
Er is een wijziging in de chat (het memoveld) van een werkorder	`WorkorderChatChanged`

Inkoop

Endpoint: /api/v1/PurchaseOrder

Notificatie	Naam
Een nieuwe inkooporder is gemaakt	`PurchaseOrderCreated`
Een inkooporder is gewijzigd	`PurchaseOrderChanged`
De status van een inkooporder is gewijzigd	`PurchaseOrderStatusChanged`
Een inkooporder mag besteld worden	`PurchaseOrderSendToSupplier`
Een inkooporder is besteld	`PurchaseOrderSentToSupplier`
Er is een levering van een inkooporder geweest	`PurchaseOrderFirstDelivery`
Een inkooporder is compleet gemeld	`PurchageOrderFinalDelivery`
De leverdatum van een inkooporder is overschreden	`PurchaseOrderDeliveryDateDue`

Inkoopadvies

Endpoint: /api/v1/PartStock

Notificatie	Naam
Een onderdeel in een magazijn bereikt de minimale voorraad	`PartStockMinimalStock`

Uitgifte

Endpoint: /api/v1/GoodsMovement

Notificatie	Naam
Een onderdeel is uitgegeven	`PartIssue`

Planregels

Notificatie	Naam
Een planregel wordt oranje	`PlanningLineInPlanzone`
Een planregel wordt rood	`PlanningLineAfterPlanzone`

Contracten

Endpoint: /api/v1/Contract

Notificatie	Naam
De waarschuwingsdatum van een contract is verstreken	`ContractEndDateDue`

Offset bij de plandatum van een werkorder

Bij de notificatie WorkorderPlanDateDue worden ook de instellingen van de notificatie meegestuurd.

Voor dit type notificatie kan worden ingesteld hoeveel tijd vóór of na de plandatum de notificatie moet worden verstuurd.

Een voorbeeld is een notificatie die drie dagen vóór de geplande datum van een werkorder wordt verstuurd.

De property offsetType bepaalt de gebruikte tijdeenheid:

None
Day
Week
Month
Year

De property offset bevat het bijbehorende aantal dagen, weken, maanden of jaren.

Tenant

De property tenant bevat de identificatie van de tenant. Deze identificatie wordt in de basis alleen door ControlOffice zelf gebruikt.

Wanneer een externe aanbieder webhooks voor meerdere ControlOffice-tenants verwerkt, kan de tenantidentificatie worden gebruikt om een multitenantoplossing te realiseren.

Timestamp

De property timestamp bevat het tijdstip waarop de notificatie door ControlOffice is gegenereerd.

De timestamp wordt weergegeven in UTC.

Beveiliging

Webhookaanroepen kunnen worden voorzien van aanvullende HTTP-headers. Deze headers kunnen in ControlOffice worden ingesteld.

Daarnaast kunnen extra queryparameters aan de webhook-URL worden toegevoegd. Hiermee kunnen bijvoorbeeld authenticatiegegevens of andere gegevens worden meegestuurd die nodig zijn voor de ontvangende applicatie.