Integration¶
Webhooks¶
Unlike an API that requires continuous requests, the Keyclic service offers webhooks when certain events occur (see list below).
It is an easy and efficient way to call a service or application to get notifications and break free from the constant check.
Webhooks have various uses, such as :
- collect reports created for your data warehouse,
- sync reports and operations with your IS (ex: CMMIS, …),
- send notifications
Webhook creation and configuration¶
Webhooks can be created upon request from our service.
A webhook consists of the event for which you wish to be notified and a URL to where the notification should be sent.
Several webhooks can be created unlimitedly for each event type.
Event types¶
Event | Description |
---|---|
reportCreated | New report created |
reportStateChanged | Report’s state changed |
operationCreated | New operation created |
operationStateChanged | Operation’s state changed |
operationRemoved | Operation removed |
Receipt of webhook notification¶
A webhook notification is sent in JSON format in the HTTP request body to the configured URL for that webhook. It contains the event name and a payload consisting of the resource details of the event. The resource varies according to the event.
note : The resource has the same serialization when requested to the API and in a webhook notification, it is possible to run through resources linked or embedded thanks to the HAL representation of our API.
{
"event": "reportCreated",
"payload": {
"type": "Report",
"id": "b0e7e28f-5b91-4c73-875e-8f34aa03553a",
"state": "NEW",
"createdAt": "2018-02-27T10:00:00+02:00",
"updatedAt": "2018-02-27T10:00:00+02:00",
"_links": {
"feedback": "...",
"operations": "...",
"organization": "...",
"tracking": "...",
},
"_embedded": {
"stateTransitions": "...",
"tracking": "..",
}
}
}
Partial example of a webhook notification received after the a new report is created.