Setup, test and manage Web Hooks

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.

Getting started

Add a web hook
  1. Click the Business Settings menu.
  2. Click the Payroll Settings submenu.
  3. Click the Web Hooks button.
  4. Click the Add button.
    Hook__NZ__1.jpg
  5. Complete the following fields:
    • Description.
    • URL.
    • Events.
  6. Click the Save button.
    Hook__NZ__2.jpg
Add a clock in/out web hook
  1. Click the Business Settings menu.
  2. Click the Payroll Settings submenu.
  3. Click the Web Hooks button.
  4. Tick Enable clock in/clock out web hooks checkbox. Please only use this setting if you specifically require web hooks for these events.
    enable_web_hooks.jpg
Test a web hook
  1. Click the Business Settings menu.
  2. Click the Payroll Settings submenu.
  3. Click the Web Hooks button.
  4. Click the Test button.
    Hook__NZ__3.jpg
  5. Select the required event and click the Test Web Hook button.
    Hook__NZ__4.jpg
Web hook events

Web Hook Events

The Web Hook events that are currently available are:

The Web Hook events (with message data types sent) that are currently available are:

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.

Event Message Verification

Web Hook message verification is included 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 

The example below shows an example request body, signature and secret. 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's recommended that you read the content as a string without any formatting, then pass it through a HMAC hash generator library along with your secret.

Secret
OLgCtvLZU4h9GYzZgamuYGdn4e7Zk651

Signature
sha256=d33766c44cd7ce49134833e072d10866a6e021053bff7f72b92b1da07b85cd3e

Body

{
  "Id": "f62319a8e9594b1da89ee456525711ea",
  "Attempt": 1,
  "Properties": {},
  "Notifications": [
    {
      "Action": "BankAccountDeleted",
      "Type": "Test Message from Application"
    }
  ]
}

 

Maintain

Edit a web hook
  1. Click the Business Settings menu.
  2. Click the Payroll Settings submenu.
  3. Click the Web Hooks button.
  4. Click on the Webhook that needs editing.
    Hook__NZ__5.jpg
  5. Make the required changed and click the Save button.
    Hook__NZ__6.jpg
Delete a web hook
  1. Click the Business Settings menu.
  2. Click the Payroll Settings submenu.
  3. Click the Web Hooks button.
  4. Click the Delete button.
    Hook__NZ__7.jpg
  5. Click the Ok button.
    Hook__NZ__8.jpg

If you have any questions or feedback please let us know via support@nzpayroll.co.nz

 

Was this article helpful?
0 out of 1 found this helpful

Comments

0 comments

Article is closed for comments.