Introductie
Assistance Online faciliteert de mogelijkheid om externe systemen aan te spreken op basis van een event in Assistance Online.: webhooks.In dit document wordt beschreven hoe deze webhooks geconfigureerd kunnen worden.
Hiervoor moet gebruik worden gemaakt van de swaggerpagina van de api en er moet geautoriseerd zijn als superuser
Opvragen van de bestaande definities
De bestaande definities kunnen worden opgevraagd met GET /webhooks-definitions/
...
NB. Alleen de webhook definitie 'OrderStatusChanged' bestaat nu.
Opvragen van de bestaande webhooks
Met gebruik van GET /webhooks kunnen de bestaande definities worden opgevraagd.
Met gebruik van GET /webhooks/:id kan een bestaande definitie worden opgevraagd.
...
NB. Bij de aanvragen wordt per webhook dezelfde informatie terug gegegeven.
Wijzigen van een webhook of toevoegen van een webhook
Met gebruik van PUT /webhooks/:id kan een bestaande webhook worden aangepast.
Met gebruikt van POST /webhooks kan een nieuwe webhook worden toegevoegd.
De body is bij beide methode hetzelfde
| Code Block |
|---|
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Naam van deze webhook",
"webhookDefinitionName": "OrderStatusChanged", // verwijzing naar bestaande webhookdefinition
"httpConfiguration": { // configuratie waarmee bericht naar extern systeem wordt gestuurd
"method": "POST", /
"url": "https://some.url",
"username": "user", // username en password worden gebruikt voor Basic authenticatie
"password": "pwd",
"httpHeaders": [ // eventueel aanvullende headers
{
"key": "string",
"value": "string"
}
]
},
"filter": {
"filterTemplate": "string" // zie uitleg verderop in dit artikel
},
"isActive": true // statuc van de webhook.
} |
Verwijderen van een webhook
Met gebruik van DELETE /webhooks/:id kan een webhook worden verwijderd
...
NB. Deze actie kan niet meer ongedaan worden gemaakt, anders dan een nieuwe webhook configureren.
Status wijzigen van een webhook
Met gebruik van PUT /webhooks/:id/status kan een webhook ge(de)activeerd worden
...
Voor een webhook die niet actief is, worden de events in Assistance Online genegeerd en wordt er geen bericht verstuurd naar een extern systeem.
Opvragen logging
met gebruik van GET /webhooks/:id/invocations en GET /webhooks/:id/invocations/:invocationId
kan de logging worden opgevraagd
...
Instellen Filter
BIj het configureren van een webhook kan een filter worden ingesteld om meer specifiek te kunnen bepalen wanneer er informatie naar een extern systeem wordt gestuurd.
Het filter is een template dat gerenderd wordt met het bericht als input en een boolean waarde moet teruggeven. Andere resultaten leveren een exceptie.
Bijvoorbeeld:
Een gegeven orderstatus changed bericht (zonder resources)
| Code Block |
|---|
{
"orderNumber": "O-0000303",
"previousStatus": "Accepted",
"newStatus": "Assigned",
"resourceReference": "/tenants/1/orders/017a1434-117a-4d6f-8842-3fa81e0427d4",
"eventType": "nl.assistanceonline.webhooks.orderstatuschanged.v1",
"resources": {
}
} |
Een ingesteld filter van een webhook (let op escaping bij het configureren
| Code Block |
|---|
{% if newStatus == "Assigned" %}true{% else %}false{% endif %} |
Dit template levert true bij het voorbeeld bericht true en wordt het bericht verzonden.
Bij andere waarden voor newStatus wordt false geleverd en wordt het bericht niet verzonden.
Bij het afhandelen van een event in Assistance Online door een webhook, worden eerst alle resources opgehaald, waarna het filter wordt toegepast.Ook kan op basis van events automatisch emails worden verzonden door gebruik te maken van de /wiki/spaces/ACT/pages/3890479114.