Paylocity webhooks: Events, retries and polling fallback

Key takeaways

Build recovery around these boundaries:

• Paylocity's Synchronization & Webhooks guidance recommends webhooks plus scheduled polling to recover missed or unsupported changes.
• An Employee Change notification identifies a record to read, not a permanent delivery key.
• Your receiver should persist accepted work before acknowledging so a process failure does not erase the handoff.
• Your application owns processing recovery after acknowledgment, separately from Paylocity's delivery recovery.
• WebLink v2 reconciliation should cover every employee page and offboarding-relevant records, not just an active-employee view.
• Notification latency and data synchronization frequency are separate freshness properties that you must evaluate independently.

For recoverable Paylocity employee synchronization, use webhooks to start work and scheduled API reads to reconcile employee state. A 200 from your receiver is one checkpoint of several. For where webhooks sit in the wider integration, see Paylocity API architecture: authentication and data access.

A notification can fail to arrive, accepted work can fail during processing, and a change can fall outside webhook coverage. Each failure needs its own recovery mechanism.

Paylocity's Synchronization & Webhooks guidance recommends combining critical-event webhooks with scheduled polling, and calls that hybrid the best practice in most cases. Its own example of a polling cadence is once every 24 hours.

This reference covers the event catalogue, Employee Change handling, durable ingestion, failure ownership, WebLink v2 reconciliation and recovery tests. The implementation recommendations are for engineers building employee-data synchronization, not promises of provider delivery or processing guarantees.

Which Paylocity webhook events are documented?

Paylocity's Webhooks reference documents New Hire, Employee Change, Termination, Payroll Processed and Time Off Approval.

A webhook pushes a notification to your receiver. An API read requests source data. Receiving a notification does not make the read unnecessary, particularly when the notification identifies a record rather than carrying its current details.

Use the catalogue to select the relevant families. The handling boundaries below are implementation guidance, not a shared payload specification:

The catalogue does not establish one common schema or exhaustive field coverage. Before implementing a handler, identify what you can infer from that family's notification.

What an Employee Change notification tells you

An Employee Change notification identifies an employee whose current data should be retrieved. It is not a documented history of the change.

Paylocity's Employee Change Webhooks reference publishes the exact trigger list. It includes names, SSN, birth date, address and phone fields, EmpStatus, HireDate, TermDate, RehireDate, CostCenter1 to CostCenter3, PayGroup, PayType, PayFrequency, BaseRate, PrimaryPayRate, Salary, Supervisor and the WorkLocation address fields. Changes count whether they are made in HR & Payroll, through Web Link imports or through the API.

What is missing from the list matters as much for a benefits or payroll product. Deductions, benefit setup, direct deposit and custom fields are not on it. A new 401(k) deferral or a changed benefit class produces no Employee Change notification, so those domains need polling regardless of how well your receiver works.

The reference says changes are checked every minute and can produce multiple notifications. The inference is that this describes provider-side change detection, not a required client polling interval.

Apply the documented properties as follows:

Use companyId and employeeId as a work target, not a permanent deduplication key. Marking that pair as "already processed" would also discard future notifications for the same employee.

You may coalesce pending work for a record, but preserve a follow-up read if another signal arrives while processing is underway. This recovers current state; it does not reconstruct every intermediate transition.

The entire documented message is two identifiers:

{ "companyId": "GC3456789", "employeeId": "12345" }

Paylocity also advises coding for null values in webhook fields.

Future-dated changes fire when they take effect

Future-dated changes are not a separate webhook. They change when the existing webhooks fire. Paylocity sends nothing when a future-dated change is entered. It sends the notification once the future record becomes current, which happens when payroll processing moves the company onto the check date the change takes effect.

In Paylocity's own example, pay rates entered on March 6 for the March 24 check date trigger webhooks only after the March 17 payroll is processed. The same applies to future-dated new hires, department changes and terminations. A product that needs to act before the effective date, such as scheduling benefits eligibility for a new hire, has to read the temporal records rather than wait for the notification.

What the receiver must do before acknowledgment

Your receiver should acknowledge only after authorized, valid work has been durably accepted. The recommendation is to return 200 at that boundary, not after placing work in process memory.

Paylocity sets up and maintains webhook subscriptions itself, and only for active Paylocity customers or Technology Partners. Your endpoint must be publicly reachable over HTTPS with TLS 1.2. Paylocity supports basic authentication on the URL and publishes its source ranges, 198.245.157.0/24 and 192.40.49.0/24, for firewall allowlisting. It recommends one or both, plus separate sandbox and production URLs. Paylocity does not document a payload signature, so basic authentication and the IP allowlist are the sender checks available.

Implement the ingress sequence in this order:

1. Authenticate: verify the configured sender protections. Reject unauthorized requests without weakening controls to encourage redelivery.
2. Validate: check the expected structure, identifiers, values and logical limits at the trusted service layer. Treat payload values as untrusted input.
3. Resolve context: associate the request with an authorized connection and company. A syntactically valid company identifier is not sufficient authorization.
4. Persist: durably record accepted work and enough connection context to process it later. Do not acknowledge first and enqueue afterward.
5. Acknowledge: return success only after persistence succeeds. Keep the acknowledgment separate from the employee-update result.
6. Process asynchronously: let a worker retrieve current data and apply the update through a recoverable processing path.

The OWASP ASVS validation requirements, version 5.0.0, released May 30, 2025, require validation against expected values, structures and logical limits at a trusted service layer. For this receiver, validation must include the relationship between the supplied identifiers and the authorized connection.

RFC 9110's HTTP acknowledgment semantics, published June 2022, distinguish request success from completed downstream work. A 200 indicates request success; 202 indicates acceptance without completed processing and is noncommittal about eventual execution.

Those semantics neither prescribe Paylocity's retry behavior nor prove that an employee update succeeded. A successful callback response closes the ingress step, not the synchronization workflow.

Who recovers delivery and processing failures?

Paylocity's delivery recovery applies before successful delivery. Your application must recover processing failures after durable acceptance.

Paylocity's Webhooks reference lists retry-eligible responses below 100, 408, 501-504 and above 505. It explicitly says 400 is not retried. 429, 500 and 505 are absent from the table, so do not assume their retry eligibility.

Use this matrix to assign recovery responsibilities and identify the evidence needed for diagnosis:

For temporary inability to durably accept otherwise valid work, 503 is a documented retry-eligible response to use. Do not disguise authentication or validation failures as temporary outages.

Paylocity documents retrying the oldest queued notification every 30 minutes for up to 24 hours. Successful delivery permits the remaining queue to proceed. This is subscription queue recovery, not a processing SLA.

After ingestion, use bounded worker retries with backoff and jitter. Retain exhausted work, its failure reason and its disposition. Alert on exhausted work rather than silently dropping it. A transient API-read failure belongs to that worker policy; it is not a reason to reinterpret a callback response.

Both event-triggered work and reconciliation should use the same repeat-safe update path: applying current employee state repeatedly should not corrupt local state. Use per-record serialization or equivalent transactional control to prevent concurrent workers from committing stale results over newer work.

Preserve a follow-up read when another signal arrives during processing. Do not require source versions or timestamps that the documented notification does not provide. Downstream side effects need their own idempotency controls; repeat-safe employee-state writes do not make those effects repeat-safe automatically.

How to reconcile employee state through WebLink v2

The fallback job should enumerate employees through WebLink v2, retrieve required details and apply them through the same update path as webhook-triggered work.

Paylocity's Get All Employees reference defines GET /api/v2/companies/{companyId}/employees. Its response contains employee identifiers and status fields, not complete employee profiles.

The documented pagesize default is 25, and pagenumber is zero-based. includetotalcount defaults to true and controls X-Pcty-Total-Count. These statements apply to this WebLink v2 list operation.

activeOnly is not among its documented query parameters. Do not copy an active-only example from generic synchronization guidance into this endpoint's contract.

For individual details, Paylocity's Get Employee reference provides GET /api/v2/companies/{companyId}/employees/{employeeId}.

Track reconciliation through each step:

1. Start a run: record the company, run identity and expected scope. Choose an interval and a configurable API budget appropriate to the connection.
2. Enumerate every page: traverse the complete list and retain page progress and failures. A successful first-page response is not a completed enumeration.
3. Preserve status coverage: retain records with status values such as A, L and T. Keep termination-relevant records, leave states and unfamiliar values in scope; do not translate every non-active state into deletion.
4. Read required details: retrieve the individual employee data your synchronization needs. Retain record-level failures for retry rather than treating unreadable records as absent.
5. Apply shared updates: route each record through the same serialized or transactionally controlled update path used by event-triggered work. Apply an active-only business view only after recovery coverage is established.
6. Close the run conditionally: declare completion only when enumeration and all required record work succeed. Retain unresolved failures and leave the run incomplete when required work remains.

A sketch of the enumeration pass, with error handling and rate limiting left out:

def enumerate_employees(company_id, client):
    page = 0
    while True:
        resp = client.get(
            f"/api/v2/companies/{company_id}/employees",
            params={"pagesize": 25, "pagenumber": page},  # pagenumber is zero-based
        )
        rows = resp.json()
        if not rows:
            return
        for row in rows:  # employeeId, statusCode, statusTypeCode only
            enqueue_detail_read(company_id, row["employeeId"])
        page += 1

Run every employee through the same enqueue_detail_read path the webhook worker uses, and never terminate a local record just because a page failed.

Choose the interval from your acceptable missed-change delay and available API capacity. A nightly schedule may be an illustrative starting point, but it is neither a Paylocity requirement nor a guaranteed freshness bound.

Budget for enumeration, detail reads, retries and webhook-driven reads together. Get All Employees documents 429 as an API response: handle throttling in the read path independently of webhook delivery, with deferred retries and retained work.

A failed read, incomplete list or absent record must not automatically terminate an employee locally. Mutable pagination does not establish a consistent snapshot, and inaccessible records cannot be guaranteed recoverable by one run. A completed run demonstrates that its required work succeeded, not that every historical transition was recovered.

How to test recovery and monitor convergence

Recovery is demonstrated by employee-state convergence after exercised failures, not by successful callback responses alone.

The following are application acceptance tests. Local fault injection or mocked callbacks do not establish observed Paylocity redelivery. Exercise the provider-recovery path only with authorized sandbox/provider coordination.

Retain evidence at each recovery boundary:

Monitor the age of oldest pending work, failed work, last successful reconciliation and reconciliation mismatches. Set alert thresholds from your application's freshness requirements, not an invented provider or industry threshold.

A recovery test should connect durable receipt to processing outcome, failed-work disposition, reconciliation completion and observed state convergence. If that chain ends at acknowledgment, the test has proved only the receiver boundary.

What a unified API changes about webhooks, and what it doesn't

Paylocity's model is a hint plus a read: two identifiers, no event ID, no timestamp, no signature, and a 24-hour retry window after which the queue waits for a person. You build deduplication, ordering and the polling fallback yourself.

Bindbee, which has a live Paylocity connector, takes a different shape. It syncs each Paylocity connection on a schedule, every 24 hours by default and adjustable on request, and sends webhooks after each sync:

• One created and one updated event per changed model, then connector.sync.completed.
• An id on every event that stays the same across retries, so deduplication is a lookup.
• A per-connector sequence, so you can skip events older than state you already hold.
• Standard Webhooks signatures that cover a timestamp, so you can reject a replayed request.
• connector.relink_needed, fired once when a customer's connection breaks.

The trade is freshness. Bindbee events report what a sync found. A termination entered in Paylocity this morning reaches you after the next sync, not within the minutes Paylocity's own webhooks allow. If that gap matters, ask for a shorter interval, force a resync for the connector, or keep Paylocity's webhooks for the few events that cannot wait.

Recovery still has an owner. Bindbee retries a failed delivery up to four times within about a minute, then stops; there is no redelivery or replay. Missed events are recovered by reading each model with modified_after set to the start of the gap. That is the same reconciliation sweep this guide recommends, run against one API instead of two Paylocity API families.

To work through sync interval, notification and recovery requirements for your Paylocity customers, see the Paylocity integration page or book a Bindbee demo.

Frequently asked questions

What webhooks does Paylocity offer?

New Hire, Employee Change, Termination, Payroll Processed and Time Off Approval. Paylocity sets up and maintains the subscriptions itself, and only for active Paylocity customers or Technology Partners.

What does a Paylocity webhook payload contain?

An Employee Change notification carries only companyId and employeeId. There is no event ID, timestamp or changed-field list, so re-read the employee through the API to get current state.

How does Paylocity retry failed webhooks?

It retries the oldest queued notification every 30 minutes for up to 24 hours. Responses below 100, 408, 501 to 504 and above 505 are retry-eligible; a 400 is never retried. After that, contact webservices@paylocity.com.

How do I secure a Paylocity webhook endpoint?

Serve it over HTTPS with TLS 1.2, add basic authentication to the URL, and allowlist 198.245.157.0/24 and 192.40.49.0/24. Paylocity does not sign payloads, so those are the sender checks available.

Do future-dated changes trigger Paylocity webhooks?

Not when they are entered. The notification fires once payroll processing moves the company onto the check date the change takes effect, which can be weeks later.