🚧
Early Adopter Opportunity
The Webhooks API is in early adoption and available only to approved early adoption (EA) partners and customers. Do not rely on this version for production workloads unless explicitly authorized. If you have any feedback, please share with your designated Early Adoption program representative.

Webhook Events

The Events API gives you visibility into webhook activity for your subscriptions.

Each event Paylocity attempts to deliver is recorded, whether or not the delivery was successful. You can use the Events API to:

Review webhook activity
Check the delivery status of an event
Troubleshoot failed deliveries
Review individual delivery attempts
Identify events that may need to be reconciled after an endpoint outage or other delivery issue

For details about the events available through Paylocity Webhooks, see Webhooks Event Types.

List Events

GET /apiHub/webhooks/v1/events

Use this endpoint to retrieve webhook events and narrow the results using filters, sorting, and pagination.

Query Parameter	Description
`filter`	Filters the events returned. Supported fields include: `subscriptionId` (in), `type` (in), `status` (in), `time` (ge, le), `applicationId` (eq), `clientId` (eq)
`limit`	Number of events returned per page. The default and maximum value is `25`.
`include`	Includes related resources in the response. Use `logs` to include details about individual delivery attempts.
`offset`	Specifies the starting position when retrieving additional results.
`sort`	Controls the order in which events are returned.
`includeTotalCount`	Controls whether the total number of matching events is included in the response.

Example: Find failed events

The following example retrieves failed events for a specific subscription beginning at a specified time:

curl -X GET "https://dc1demogwext.paylocity.com/apiHub/webhooks/v1/events?filter=status in ('Failed') and subscriptionId in ('YOUR_SUBSCRIPTION_ID') and time ge '2024-01-15T00:00:00Z'&limit=25&sort=-time" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

Understanding an Event

Each event includes information about what occurred and what happened when Paylocity attempted to deliver it.

Field	Description
`id`	Unique identifier for the webhook event
`correlationId`	Identifier that can be used to trace the event across systems.
`subscriptionId`	ID of the subscription associated with the event.
`subscriptionName`	Name of the subscription associated with the event.
`type`	Event type, such as `employee.person.v1`.
`mutation`	Type of change that occurred: `created`, `updated`, or `deleted`.
`time`	Time the underlying change occurred.
`data`	Event payload. The information included varies by event `type`.
`status`	Current delivery status: `Delivered`, `Failed`, or `Pending`.
`lastStatusCode`	HTTP status code from the most recent delivery attempt.
`totalAttempts`	Total number of delivery attempts made for the event.
`logs`	Details for individual delivery attempts when `include=logs` is requested. Each log includes `responseCode`, `attemptNumber`, `durationMs`, and `createdAt`.

Viewing Delivery Attempts

To troubleshoot an event in more detail, include logs in your request:
include=logs

The returned logs provide information about each delivery attempt, including:

Response code
Attempt number
Duration
Time of the attempt

This can help you understand what occurred across multiple delivery attempts instead of looking only at the event's current status.

Delivery Status

Paylocity considers a webhook delivered when your endpoint returns an HTTP response, including a 4xx or 5xx response.

A delivery is considered undeliverable when Paylocity cannot receive a response from your endpoint, such as when a timeout or connection error occurs. Undeliverable events may be eligible for retry.

Important: An HTTP response indicates that the webhook reached your endpoint. A 4xx or 5xx response is therefore still considered delivered for webhook delivery-status purposes.

Recovering Missed Events

If your endpoint experiences downtime or another delivery issue, you can use the Events API to identify events that may require reconciliation.

For example, use the time filter to search the affected time period and filter for events with a Failed status:

status in ('Failed')

After identifying the affected events, use the event's data and the applicable Paylocity read API to reconcile the current state of the affected resource.