The Rotageek API exposes webhooks as a means of being notified when events in the system have occurred so your system can act upon them.
Events Available:
SchedulerApproved // When a new schedule is approved
UsersChanged // When users are updated
TimeSheetSignedOff // When a timesheet is signed off
GapsUpdated // When a gap is updated
PayrollTriggered // When payroll is triggered
LeaveUpdated // When leave is updated
Using webhooks:
To add a webhook use the POST/api/v1/webhooks endpoint. We also offer GET/PUT/DELETE for CRUD operations on your webhooks.
When adding a new webhook that should be triggered on an event in the system, the EventName should be set as one of the option described below. Multiple endpoints can be assigned to the same event but endpoints cannot have the same value. Please note it may take up to 10 minutes after registering a webhook before you recieve the first events.
SchedulerApproved Webhook Event Example:
An example how to add a webhook for the scheduler approved event:
{
"EventName": "SchedulerApproved",
"Uri": "http://<receiving_address>/receive",
"Secret": "Ki*p3(8%%c-78gYYt"
}
After webhook has been successfully added, every time schedule is approved a new POST request will be sent to a receiving endpoint. Example of POST request for a SchedulerApproved webhook event:
{
"Timestamp":"2018-07-06T16:37:52.0950029+00:00",
"UniqueId":"0f148fac-1379-423d-94cd-775693d54fe3",
"Event":"SchedulerApproved",
"Data":
{
"locationUniqueId":"uniqueLocationId",
"from":"2018-07-30T16:37:41.9510797+00:00",
"to":"2018-08-06T16:37:41.9530847+00:00"}
}
}
On receiving a webhook POST latest schedule data for that location can be acquired using /api/v1/schedule/locations/<uniqueLocationId> with from and to as a filtering parameters.
UsersChanged Webhook Event Example:
An example of how to add a webhook for the users changed event:
{
"EventName": "UsersChanged",
"Uri": "http://<receiving_address>/receive",
"Secret": "Ki*p3(8%%c-78gYYt"
}After webhook has been successfully added, every time a user has been created, updated or deleted a new POST request will be sent to a receiving endpoint. Example of POST request for a UsersChanged webhook event:
{
"Timestamp":"2018-07-06T16:37:52.0950029+00:00",
"UniqueId":"0f148fac-1379-423d-94cd-775693d54fe3",
"Event":"UsersChanged",
"Data":
{
"Users":["userId1","userId2","userId3"]}
}
}
On receiving a webhook POST for a UsersChanged webhook event, further user data can be acquired using /api/v1/users?userId=<userId1> with userId as a filtering parameter.
TimeSheetSignedOff Webhook Event Example:
An example how to add a webhook for the time sheet signed-off event:
{
"EventName": "TimeSheetSignedOff",
"Uri": "http://<receiving_address>/receive",
"Secret": "Ki*p3(8%%c-78gYYt"
}After webhook has been successfully added, every time a time sheet is signed-off a new POST request will be sent to a receiving endpoint. Example of POST request for a TimeSheetSignedOff webhook event:
{
"Timestamp":"2018-07-06T16:37:52.0950029+00:00",
"UniqueId":"0f148fac-1379-423d-94cd-775693d54fe3",
"Event":"TimeSheetSignedOff",
"Data":
{
"locationId":"uniqueLocationId",
"weekStartDate":"2022-04-21T00:00:00.0000000+00:00",
}
}
On receiving a webhook POST latest time sheet data for that location can be acquired using /api/v1/timesheets/locations/<locationId>/<weekStartDate>.
Gap changed Webhook Event Example:
An example how to add a webhook for the gap changed event:
{
"EventName": "GapsChanged",
"Uri": "http://<receiving_address>/receive",
"Secret": "Ki*p3(8%%c-78gYYt"
}After webhook has been successfully added, every time a time a gap is created or modified a new POST request will be sent to a receiving endpoint. Example of POST request for a GapsChanged webhook event:
{
"Timestamp":"2018-07-06T16:37:52.0950029+00:00",
"UniqueId":"0f148fac-1379-423d-94cd-775693d54fe3",
"Event":"GapsChanged",
"Data":
{
"gapIds":["UniqueIdOfUpdatedGap1","UniqueIdOfUpdatedGap2"]
"locationId":"uniqueLocationId",
"from":"2022-04-21T09:00:00.00",
"to":"2022-04-23T17:00:00.00",
}
}
On receiving a webhook POST the latest data for the affected gaps can be acquired using api/v1/gaps/locations?locationIds=locationId&from=from&to=to.
Security:
To ensure the security of clients there is a signing mechanism built-in into webhook messages. When a client is setting up a new webhook a secret must be provided. The secret must be between 8 and 256 symbols long and should be hard to guess. This secret should be known for the client after webhook creation. The secret is kept in the server encrypted and is used to create a signature for the webhook request. The signature is attached to every request in request headers:
"signature": "sha256=<signature>"
Signature is generated using HMACSHA256. To validated message HMACSHA256(<raw_message_data>, <secret>) should be equal to <signature> from hex string. The client needs to validate message against signature to make sure that request comes from a valid source and that the message integrity was not compromised. Each webhook request must have a valid timestamp and unique id generated for that specific request.