Web Hooks allow an external URL to be called upon certain events occurring in the system. For example, when an employee is created or when a leave request is created. For more information about web hooks, please refer to this Wikipedia Article. Web Hooks can also facilitate integration with services such as Zapier and IFTTT allowing powerful options for data integration between systems.
Adding a Web Hook
To add a web hook, go to Payroll Settings -> Advanced -> Web Hooks. Then click the 'Add' button and enter:
- A description for the web hook
- A URL that should be called
- The events that will trigger this particular web hook
Once a Web Hook has been set up, it will become active immediately.
Testing Web Hooks
To test the web hook, either do the action that triggers the web hook or click on the 'Test Web Hook' button.
When testing the web hook using the 'Test' button, the a small basic set of data will be sent. This is not representative of the actual data that will be sent to the web hook.
Web Hook Events
The Web Hook events (with message data types sent) that are currently available are:
- Employee Created (UnstructuredEmployeeModel)
- Employee Terminated (UnstructuredEmployeeModel)
- Employee Updated (UnstructuredEmployeeModel)
- Pay Run Finalised (PayRunModel)
- Pay Run Deleted (pay run ID)
- Pay Run Initialised (PayRunModel)
- Leave Request Created (HourLeaveRequestResponseModel)
- Bank Account Deleted (bank account ID)
- Bank Account Updated (BankAccountModel)
- Employee Recurring Deduction Deleted (deduction ID)
- Employee Recurring Deduction Updated (EmployeeRecurringDeductionModel)
- Leave Request Updated (HourLeaveRequestResponseModel)
- Leave Request Cancelled (HourLeaveRequestResponseModel)
- Leave Request Declined (HourLeaveRequestResponseModel)
- Leave Request Approved (HourLeaveRequestResponseModel)
- Leave Request Created (HourLeaveRequestResponseModel)
Data is sent inside a wrapper class (Microsoft.AspNet.WebHooks.WebHookWorkItem). eg:
{
"Id": "62b45c1f7584400193a0879a163897b2",
"Attempt": 1,
"Properties": {},
"Notifications": []
}
With the relevant data inside the Notifications array
Retry Intervals
If the call to the web hook URL does not return a 'success' result (for example a HTTP 200 or HTTP 201), it will be retried at increasingly higher delays.
- First attempt: Immediate
- Retry 1: 1 minute after first attempt
- Retry 2: 2 minutes after previous retry
- Retry 3: 4 minutes after previous retry
- Retry 4: 8 minutes after previous retry
- Retry 5: 15 minutes after previous retry
- Retry 6: 30 minutes after previous retry
- Retry 7: 1 hour after previous retry
If the web hook attempt is still not successful after 7 retries, it will not be re-attempted.
If you have any questions or feedback please let us know via support@yourpayroll.io