Using webhooks

To add a webhook the /webhooks/ endpoint should be used. 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.