Webhooks

No modern REST API is complete without webhooks. We've implemented them following the approach outlined by resthooks.org.

What are Webhooks?

If System A wants to know if data has changed in another application - let's call it System B - then the way it's often done is with what's called "polling". System A will, at regular intervals, check in with the System B to get a list of items and it'll compare it to it's previous list to see if anything has been added or removed.

That's not efficient.

Enter Webhooks.

System A provides its users with a URL that can receive data. The user then logs on to System B and pastes in that URL to a webhook.
Then, whenever something changes in System B (an 'event') it will send a message to the URL in System A to let it know about the change.

Better, but not perfect

Resthooks

Resthooks build on top of the concept of Webhooks. They work in the same way but are much easier for non-technical users to set up.

Rather that copying-and-pasting a URL, the subscription to events is done via an API so from the users perspective they just click a link to confirm they want to give System A the ability to receive notifications about their data in System B.

Our Implementation

You can Subscribe and Unsubscribe to events via the API.

Currently supported events are:

  • Employee Created
  • Employee Updated
  • Employee Deleted
  • Payrun Finalised
  • Payrun State Changed
  • Pension Membership Created
  • Pension Membership Updated
  • Pension Membership Deleted
  • Job Completed
If there are events you need that aren't listed then get in touch as we should be able to add them.

Webhooks will automatically deactivate if they receive a 410 - Gone response.

Urls are always POSTed to with a JSON representation of the relevant data.

Although - as with everything else in the application - webhooks can be managed purely via the API, you may find the User Interface useful to debug and manage them.
When logged in to an account, click the Employer name in the main menu, go to Settings -> Webhooks

As well as easily creating and updating webhooks you can also view the events, JSON payloads and response codes for each time the event has been triggered.

Data is always sent as an array of one item. You can view example payload data via this API call.