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 InformationThe 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 parameter | Description |
|---|---|
filter | Filter expression. Filterable fields: subscriptionId (in), type (in), status (in), time (ge, le), applicationId (eq), clientId (eq) |
limit | Maximum number of events to return. Default and maximum: 25 |
offset | Number of events to skip. Default: 0 |
sort | Comma-separated list of fields to sort by, for example -time for newest first |
include | Use logs to include delivery attempt logs for each event |
includeTotalCount | When 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 parameter | Description |
|---|---|
include | Comma-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
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique event ID. Matches the id in the delivered payload. |
correlationId | string (UUID) | Identifier used to trace the event across systems |
subscriptionId | string (UUID) | ID of the subscription the event was delivered to |
subscriptionName | string | Name of that subscription |
clientId | string | ID of the API credentials that own the subscription |
applicationId | string (UUID) | ID of the application associated with the API credentials |
type | string | Event type, for example employee.person.v1 |
mutation | string | created, updated, or deleted |
time | string (date-time) | When the event occurred |
dataContentType | string | Content type of the event payload |
data | object | The event payload. Structure varies by event type. |
status | string | Delivery status: Delivered, Failed, or Pending |
lastStatusCode | string | HTTP status code returned by your endpoint on the most recent attempt |
totalAttempts | integer | Total number of delivery attempts made |
logs | array | Delivery attempts. Returned when include=logs is used. |
subscription | object | The subscription configuration. Get Event [Single] only, when include=subscription is used. |
Delivery log entry
Each item in logs:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique identifier of the log entry |
attemptNumber | integer | The delivery attempt number |
responseCode | string | HTTP status code returned by your endpoint for this attempt |
response | string | Response body returned by your endpoint for this attempt |
durationMs | integer | Duration of the attempt in milliseconds |
createdAt | string (date-time) | When the attempt was made |
Delivery statuses
| Status | Meaning |
|---|---|
Pending | Queued or waiting for a retry |
Delivered | Your endpoint returned a 2xx response |
Failed | Delivery stopped without success |