Paylocity Webhooks enables system triggered notifications for application events.
Overview
Paylocity APIs are provided as a way to build a secure communication channel between the Paylocity product suite and another external system. For example, using our APIs, you can poll a list of employees from Paylocity at regular intervals or you could push changes from your system into Paylocity as needed. However, what if you need to react to a change in the Paylocity status of an employee, such as employment termination? Webhooks enables an integration to be responsive, notifying your system that something important changed in the Paylocity application and may require immediate attention and/or action.
What are Webhooks?
Instead of continuously polling a server for updates or changes, Webhooks allow the Paylocity application to notify an external system automatically when a specific event occurs. Webhooks are automated JSON POST messages transmitted via HTTPS, sent to a unique URL that you've configured for your system to listen for these notifications.
The URL provided must be publicly accessible. While you can put basic authentication on the URL for security (in fact, we recommend it) the URL itself must be one to which Paylocity can send an HTTPS request. In practice, this means that using a local development computer may not be feasible unless it's been setup with the appropriate networking configurations to create a publicly-accessible IP address that can pass requests to the local web application server.
Best Practices
- When setting up a URL to receive Webhook messages, it is strongly encouraged to secure access with a username and password that can be used by Paylocity when sending the notification. Alternatively, blocking access to the URL unless it comes from an authorized IP address (Paylocity IPs are listed below) is also recommended. One or both configurations will help to mitigate the risk of malicious actors disrupting an integration or sending false information to your system.
- Have separate Webhook URLs for sandbox and production environments, because we don't want to cross-contaminate live data with test data.
- In general, don't rely on the Webhooks notification to give you all the information changed, instead make a call to the relevant APIs after receiving a Webhooks notification to get the latest details; in some cases, especially related to employee information, a single user triggered change may result in additional automated system changes to that data object. Calls can be made using the company and ID values provided from the Webhook.
- Coding should be in place to expect null values for the fields sent in the Webhook notification.
- In the event that an error occurs during transmission of a Webhook notification, an error will be logged that a Paylocity client company admin may review. The company admin may then request Paylocity resend the notification, but should first verify that the notification was truly not received by the listening system or risk duplicating data/processes.
Available Webhooks
Below are the automation triggers currently supported with Webhooks from the Integrations platform. Paylocity is in the process of adding more triggers based on company input and business requirements.
Automation triggers currently supported with Webhooks
Whitelist Paylocity IP addresses
You may need to add the following Paylocity IP addresses to your firewall(s) for the Webhooks to be received.
Source IP addresses for Webhooks notification:
- 198.245.157.0/24
- 192.40.49.0/24
Requesting Webhooks Setup
Webhooks are set up and maintained by Paylocity. Below you will find a checklist of perquisites and steps to contacting the appropriate group to get Webhooks setup for a sandbox or production environment.
Prerequisites
- Webhooks configuration are only available for active Paylocity customers or Technology Partners
- Identify which webhooks will need to be configured
- Setup a publicly-accessible URL to receive the Webhook notifications
- Configure access to the URL (username & password or/and firewall restrictions)
Contacting Paylocity
- Technology Partners will contact their assigned Business Development liaison
- Prospective Technology Partners will contact a Business Development liaison via Connect With Us Today form
- Paylocity customers will send a request email to [email protected]