Overview

Keeping records in sync across systems is critical for smooth operations and security. At its core, record synchronization underpins provisioning and deprovisioning workflows—helping guarantee that services, applications, and permissions are granted or revoked in a timely manner.

Methods for record synchronization

👍

Recommended - Hybrid; combining webhooks with polling

We recommend all integrators use the Hybrid approach for record syncing. Set up webhooks for critical, high priority events and run a background polling job on a defined schedule. Webhooks capture time-sensitive events and polling ensures you catch any missed or unsupported event types.

Method details

This section will provide a deep dive into each of the methods for record synchronization, providing further information on the pros and cons of each.

Hybrid

Overview: Combining both Polling & Webhooks (Best Practice)

The hybrid approach sets up webhooks for critical, high priority events and runs a background polling job on a defined schedule. For instance, you can perform daily polling while also responding to real-time webhook notifications.

Benefits of a Hybrid Design:

• Full Coverage – Webhooks capture time-sensitive events; polling ensures you catch any missed or unsupported event types.
• Real-Time + Fallback – Enjoy the responsiveness of event-driven updates without worrying about incomplete coverage.
• Flexible Rate Usage – Lower overall API usage compared to frequent polls alone, while still receiving critical updates quickly.

Considerations of a Hybrid Design:

• Increased Complexity – Requires managing two integration methods simultaneously
• Overlap in Updates – Reconciliation logic may be required to avoid double-processing the same changes.
• Scheduling: Determine a reasonable polling interval (e.g., daily, weekly) based on how often data changes outside of covered webhook events.
• De-Duplication: Implement a mechanism (e.g., record version IDs or timestamps) to detect if a record has already been updated via webhook before a poll processes it again.
• Prioritization: Use webhook updates immediately and reserve polling for “backfill” or less time-sensitive changes.

Polling

Overview:

Polling involves calling an API endpoint at a regular interval and retrieving the latest available data. For example, a system might call the OpenAPI’s Employee endpoint (e.g., GET /employees) once every 24 hours; or once a week, depending on the specific applications needs; and the overall headroom available with the rate-limit against the total number of records you wish to synchronize.

Benefits of Polling

• Simplicity – Easy to implement and understand.
• Reliable Fallback – Even if certain events go unreported, a thorough poll can catch all changes eventually.
• Control Over Timing – You can tune the frequency of polls (e.g., hourly, daily) to balance data freshness with API call consumption and rate-limiting. The consideration for this control should be on a per-endpoint basis according to your application needs.

Considerations of Polling

• Higher API Usage – Frequent polling can lead to heavy API requests, approaching rate limits if not carefully managed.
• Latency – Data may become stale between poll intervals. A weekly poll might leave your system out of date compared to a nightly poll every 24 hours.
• Rate Limits: Familiarize yourself with the rate limits (e.g., 25 requests per second) to avoid throttling or being blocked (HTTPS Error 429)
• Incremental Fetches: Use query-parameters and/or batch endpoints, when possible, to reduce data load. Ex: Query-Parameter on GET Employee for activeOnly; or Filter-Parameter for “status ne terminated”; which would provide all non-terminated records.
• Error Handling: Implement retry logic to handle transient network or API errors. Ensure that if your polling job fails on a record, it does not fall all other records related to the job-run.

Webhooks

Overview:

Webhooks provide real-time or near real-time notifications for events. When a specific event—such as Employee New Hire, Employee Termination, or Employee Change—occurs, the source system (i.e., the system that owns the data) sends a POST request to a predetermined “callback” URL on your receiving system.

Benefits of Webhooks

• Real-Time Updates – Data changes are pushed almost immediately, reducing latency and improving responsiveness between systems and by extension the services related to the data over the integration.
• Reduced API Calls – You do not need to poll as often, reducing overhead and API usage. This also has cost-saving implication if you are using a 3rd party software to complete the calls, as those services often have a cost-to-call consideration.

Considerations of Webhooks:

• Event Gaps – If an event/data-element is not covered by a webhook, changes might go undetected unless you have a fallback mechanism such as polling from above.
• Data Enrichment: The webhook payload may be lightweight. Often, you will still need to call the API for full details on the changed or new employee record.
• Delivery Failures – Handling potential failures or delays in the source system’s attempt to deliver events is critical. Understanding that not all HTTPS errors result in RETRY attempts with Paylocity is critical; in addition to understanding the concept of our Webhook Triage queue principles.
• Security: Ensure your receiving endpoint uses TLS 1.2 and that you verify the authenticity of incoming requests. Paylocity offers Basic Authentication for endpoints if needed.