Werken met webhooks
Een webhook wordt ook wel een HTTP push of een web callback genoemd. Het is een manier om een doel applicatie te voorzien van nieuwe of gewijzigde gegevens.
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'.
Bij het versturen van een notificatie van het type webhook, wordt een POST request gedaan naar de URL die geconfigureerd is[1]. Dus in het geval van bovenstaand voorbeeld wordt het volgende request uitgevoerd:
POST https://webhookreceiver.nl
De body van dat request bevat een JSON object met de volgende inhoud[2]:
{
"subjectType": "<naam notificatie-type>",
"subjectId": "<identificatie van subject>",
"offsetType": "<type offset>",
"offset": "<offset>",
"timestamp": "<timestamp, UTC>"
}
Het subjectType bevat het type van de notificatie, bv. “RequestCreated” is het notificatietype voor als er een nieuwe melding is gemaakt in ControlOffice. Het subjectId bevat de identificatie van het onderwerp. Het subjectId van een webhook request met subjectType “RequestCreated” bevat de interne identificatiecode van een melding (een Request).
Hiermee zou dus, vanuit de ontvanger van de webhook een request naar de ControlOffice API gedaan kunnen worden, om de desbetreffende melding op te halen en er vervolgens wat mee te doen.
GET /api/v1/Request/<interne identificatiecode>
Niet alle type notificaties hebben een subjectId; bv. de notificaties voor planregels die in of na de planzone zijn gekomen, bevatten geen subjectId.
In offsetType wordt het type offset vastgelegd (d.i. None, Day, Week, Month, Year) en in offset een aantal (bv. stuur een notificatie indien een werkorder 2 dagen laten gepland is). Dit is alleen valide bij subjectType “WorkorderPlandateDue”. Bij het verwerken van de webhook kan eventueel een beslissing genomen worden o.b.v. deze informatie.
De timeStamp bevat het tijdstip waarop de notificatie is ontstaan.
In onderstaande tabel wordt dit uitgelegd[3]:
|
SubjectType |
Gebeurtenis |
Subject Id verwijzing |
|
RequestCreated |
Er is een nieuwe melding gemaakt |
Request |
|
RequestChanged |
Een melding is gewijzigd |
Request |
|
RequestStatusChanged |
De status van een bestaande melding is gewijzigd |
Request |
|
RequestMarkedReady |
Een melding is gereed gemeld |
Request |
|
RequestCancelled |
Een melding is geannuleerd |
Request |
|
WorkorderCreatedFromRequest |
Er is een werkorder gemaakt van een melding |
Request |
|
WorkorderCreated |
Er is een nieuwe werkorder gemaakt |
Workorder |
|
WorkorderChanged |
Een werkorder is gewijzigd |
Workorder |
|
WorkorderStatusChanged |
De status van een bestaande werkorder is gewijzigd |
Workorder |
|
WorkorderResponsibleSet |
Er is een verantwoordelijke voor een werkorder aangewezen |
Workorder |
|
WorkorderResponsibleRemoved |
Er is een verantwoordelijke van een werkorder verwijderd |
Workorder |
|
WorkorderEmployeeCreated |
Er is een medewerker aan een werkorder toegevoegd |
Workorder |
|
WorkorderEmployeeRemoved |
Er is een medewerker van een werkorder verwijderd |
Workorder |
|
WorkorderPlandateDue |
De plandatum van een werkorder komt binnen de ingestelde offset-periode |
Workorder |
|
WorkorderMarkedReady |
Een werkorder is (technisch) gereed gemeld |
Workorder |
|
WorkorderCompleted |
Een werkorder is compleet gemeld |
Workorder |
|
WorkorderClosed |
Een werkorder is gesloten |
Workorder |
|
WorkorderChatChanged |
De “chat” van een werkorder is gewijzigd |
Workorder |
|
PurchaseOrderCreated |
Een nieuwe inkooporder is gemaakt |
PurchaseOrder |
|
PurchaseOrderChanged |
Een inkooporder is gewijzigd |
PurchaseOrder |
|
PurchaseOrderStatusChanged |
De status van een bestaande inkooporder is gewijzigd |
PurchaseOrder |
|
PurchaseOrderSentToSupplier |
Een inkooporder is als verzonden gemarkeerd |
PurchaseOrder |
|
PurchaseOrderFirstDelivery |
De eerste levering op een inkooporder is ontvangen |
PurchaseOrder |
|
PurchaseOrderFinalDelivery |
De laatste levering op een inkooporder is ontvangen, de volledige inkooporder is compleet geleverd gemeld |
PurchaseOrder |
|
PurchaseOrderDeliveryDateDue |
De leverdatum van een inkooporder komt binnen de ingestelde offset-period |
PurchaseOrder |
|
PartStockMinimalStock |
De minimale voorraad van een magazijn-onderdeel is bereikt |
PartStock |
|
PartIssue |
Een onderdeel is uitgegeven |
GoodsMovement |
|
PlanningLineInPlanzone |
Er zijn planregels die in de planzone vallen |
|
|
PlanningLineAfterPlanzone |
Er zijn planregels die na de planzone vallen |
|
|
ContractEndDateDue |
De waarschuwingsdatum op een contact is verstreken |
Contact |
|
BackgroundImportStarted |
Een importeer-actie is gestart |
|
|
BackgroundImportFinished |
Een importeer-actie is beëindigd |
|
1. In de toekomst zal het ook mogelijk zijn om custom headers toe te voegen aan het webhook request. Dit moet dan per notificatie ingesteld worden.
2. De body wordt binnenkort uitgebreid met de property “tenantId”, met een verwijzing naar de identificatie van de tenant.
3. Deze lijst is aan verandering onderhevig.