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

• New Hire Webhooks
• Employee Change Webhooks
• Termination Webhooks
• Payroll Processed Webhooks
• Time Off Approval 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 our contact form
• Paylocity customers will send a request email to [email protected]

Undeliverable Webhooks

Paylocity attempts to resend webhook notifications for configured integrations when certain actions or events happen for the subscription. When Paylocity receives an undeliverable response or no response from a URL for a webhook, Paylocity queues the undelivered notification and initiates an automated retry process.

Once the queue process begins, Paylocity attempts to resend the oldest webhook in the queue every 30 minutes for up to 24 hours. If the webhook delivers successfully, Paylocity will process the rest of the webhooks and restore normal operations for the subscription. If the webhook cannot be delivered within 24 hours, Paylocity will continue to queue new messages, but no longer automatically tries to resend. Contact [email protected] for assistance with undeliverable webhooks.

Delivered with errors

When Paylocity sends a webhook to a client or vendor system, it considers the webhook delivered if a response is received indicating that the system attempted to process the notification—regardless of whether the response indicates success or failure of that processing.

Example: If the receiving system responds with a 400 Bad Request error, Paylocity will not retry the delivery. The webhook reached its destination, but the receiving system was unable to process it. These cases are classified as processing errors, not delivery failures and such errors should be handled via internal logging, alerting, and the support team managing the receiving system.

Only when no response is received at all or the response indicates an error in transport to the listening system—such as a timeout or network failure—does Paylocity classify the webhook as undeliverable, and may retry depending on the configuration.

Webhook subscriptions that receive the below response codes will be queued for attempted resending: