Events

How to read the history of webhook events that were sent, check delivery status, and recover from missed deliveries.

🚧

Early Access (EA)

This API is currently in Early Access and available only to approved EA participants. 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.

Overview

The Events endpoints give you visibility into webhook activity for your subscriptions. Every event Paylocity attempts to deliver is recorded, whether or not delivery succeeded.

Use them to:

  • Review webhook activity
  • Check the delivery status of an event
  • Troubleshoot failed deliveries
  • Review individual delivery attempts, including the response your endpoint returned
  • Find events to reconcile after an endpoint outage
📘

Additional Information

The Events endpoints are for auditing. Your application receives events at its callback URL. It does not need to call these endpoints to receive them.

Get Events [Batch]

GET /apiHub/webhooks/v1/events

Query parameterDescription
filterFilter expression. Filterable fields: subscriptionId (in), type (in), status (in), time (ge, le), applicationId (eq), clientId (eq)
limitMaximum number of events to return. Default and maximum: 25
offsetNumber of events to skip. Default: 0
sortComma-separated list of fields to sort by, for example -time for newest first
includeUse logs to include delivery attempt logs for each event
includeTotalCountWhen true, returns the total number of matching events in the X-Pcty-Total-Count response header. Default: false

Example: find failed events

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

Get Event [Single]

GET /apiHub/webhooks/v1/events/{id}

Returns one event by its id (UUID). Use it to inspect a specific event, for example an event id from a delivery your endpoint logged.

Query parameterDescription
includeComma-separated. logs includes delivery attempt logs. subscription includes the subscription configuration the event was delivered to.
curl -X GET "https://dc1demogwext.paylocity.com/apiHub/webhooks/v1/events/YOUR_EVENT_ID?include=logs,subscription" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Event record

FieldTypeDescription
idstring (UUID)Unique event ID. Matches the id in the delivered payload.
correlationIdstring (UUID)Identifier used to trace the event across systems
subscriptionIdstring (UUID)ID of the subscription the event was delivered to
subscriptionNamestringName of that subscription
clientIdstringID of the API credentials that own the subscription
applicationIdstring (UUID)ID of the application associated with the API credentials
typestringEvent type, for example employee.person.v1
mutationstringcreated, updated, or deleted
timestring (date-time)When the event occurred
dataContentTypestringContent type of the event payload
dataobjectThe event payload. Structure varies by event type.
statusstringDelivery status: Delivered, Failed, or Pending
lastStatusCodestringHTTP status code returned by your endpoint on the most recent attempt
totalAttemptsintegerTotal number of delivery attempts made
logsarrayDelivery attempts. Returned when include=logs is used.
subscriptionobjectThe subscription configuration. Get Event [Single] only, when include=subscription is used.

Delivery log entry

Each item in logs:

FieldTypeDescription
idstring (UUID)Unique identifier of the log entry
attemptNumberintegerThe delivery attempt number
responseCodestringHTTP status code returned by your endpoint for this attempt
responsestringResponse body returned by your endpoint for this attempt
durationMsintegerDuration of the attempt in milliseconds
createdAtstring (date-time)When the attempt was made

Delivery statuses

StatusMeaning
PendingQueued or waiting for a retry
DeliveredYour endpoint returned a 2xx response
FailedDelivery stopped without success