Available for the following Payroll plans: Employment Lite, Employment Plus, Employment Unlimited
Available for the following Payroll classic plans: Standard, Premium
Web Hooks are one of a few ways web applications can communicate with each other and allow you to send real-time data from one application to another whenever an event occurs.
The platform sends this data online from the original application through to the receiving application that handles the data.
This exchange of data happens over the web through a Web Hook URL provided by the receiving application, which acts essentially as a phone number that the other application can call when an event happens.
You can use the Payroll Web Hooks feature to add a new Web Hook to your organisation's payroll platform and then test out this data source to make sure it works as intended. You can also use this feature to edit any information if it changes and delete a record if it is no longer required.
Getting started
- Click the Business Settings menu.
- Click the Payroll Settings submenu.
- Click the Web Hooks button.
- Click the Add button.
- Complete the following fields:
- Description
- URL
- Events
- Click the Save button.
- Click the Business Settings menu.
- Click the Payroll Settings submenu.
- Click the Web Hooks button.
- Tick the Enable clock in/clock out web hooks checkbox.
Daily activities
- Click the Business Settings menu.
- Click the Payroll Settings submenu.
- Click the Web Hooks button.
- Click the Test button.
- Select the required event and click the Test Web Hook button.
Editing data
- Click the Business Settings menu.
- Click the Payroll Settings submenu.
- Click the Web Hooks button.
- Click the Web Hook that needs to be edited.
- Make the required changed and click the Save button.
Removing data
- Click the Business Settings menu.
- Click the Payroll Settings submenu.
- Click the Web Hooks button.
- Click the Delete button.
- Click the OK button.
Further information
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), with the relevant data inside the Notification array.
If the call to the web hook URL does not return a success result (for example, a HTTP 200 or HTTP 201), we will retry the sync at increasingly high 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 not successful after seven retries, we will not re-attempt the sync.
We include Web Hook message verification with each web hook registration by computed a sha256 hash of the message payload using HMAC and web hook secret. Each event will contain the hashed value within the header response MS-Signature.
You can use an application like https://www.freeformatter.com/hmac-generator.html to test the resulting hash.
Please note the hash is sensitive to any whitespace in the request content. It is recommended that you read the content as a string without any formatting, then pass it through an HMAC hash generator library along with your secret.
Explore related content
- How do I set up and manage my organisation's calendar feed via Payroll classic? This feature allows you to turn a payroll event into a calendar feed, and then copy the link to this data source into, for example, Outlook.
- How do I set up email sender authentication via Payroll classic? This feature allows you to set up DKIM (Domain Keys Identified Mail) on a domain of your choice for emails sent via the platform.