How to create, read, update, and delete Webhooks API subscriptions.
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
A subscription tells Paylocity which events you want to receive, where to deliver them, and how to secure the delivery. You manage subscriptions through the Webhooks API.
Additional InformationSelecting event types in the Developer Portal grants your application access to those events. It does not create a subscription. You must create the subscription with the API.
Getting Started
- To enable subscriptions, you will need an integration with access to the Webhooks API and to the event types you want
- You will need your OAuth 2.0 access token for that integration (see Webhooks Authentication)
- You will need to provide a publicly reachable HTTPS endpoint to receive event deliveries
- Ideally, you will have separate endpoints for sandbox and production to facilitate testing (recommended)
Subscription object
Returned by Get Subscriptions [Batch] and Get Subscription [Single].
| Property | Type | Description |
|---|---|---|
id | string (UUID) | Unique identifier of the subscription. Generated by Paylocity. |
clientId | string (UUID) | The ID of the API credentials that own the subscription |
applicationId | string (UUID) | The ID of the application associated with the API credentials |
name | string | Name of the subscription, such as Employee Updates - Production |
status | string | Current status. See Subscription statuses. |
eventTypes | array of strings | Event types delivered to this subscription |
url | string | URL where events are delivered |
auth.type | string | Delivery signing type. Allowable value: HMAC |
auth.hmac.key1 | object | Primary HMAC key: keyId (UUID), issuedAt, expirationAt |
auth.hmac.key2 | object | Secondary HMAC key, used for key rotation: keyId (UUID), issuedAt, expirationAt. Present only when a second key exists. |
createdAt | string (date-time) | When the subscription was created |
The HMAC secret is never returned by the GET endpoints.
Create a subscription
POST /apiHub/webhooks/v1/subscriptions
Request body
| Property | Required | Type | Description |
|---|---|---|---|
name | Yes | string (max 100 characters) | Name of the subscription |
eventTypes | Yes | array of strings | Event types to subscribe to. Supported values: employee.person.v1, employee.assignment.v1, employee.assignment.status.v1, employee.assignment.payrate.v1, employee.assignment.position.v1, employee.assignment.reviewer.v1, employee.assignment.supervisor.v1, employee.assignment.costcenter.v1, employee.assignment.workcontact.v1, employee.assignment.worklocation.v1, employee.paytypetransaction.v1, employee.workedshift.v1 |
url | Yes | string | The HTTPS URL where events will be delivered |
auth | Recommended | object | HMAC signing configuration for deliveries to your url. Set type to HMAC and provide hmac.key1.expirationAt (date-time). |
Example request
curl -X POST "https://dc1demogwext.paylocity.com/apiHub/webhooks/v1/subscriptions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Employee Updates - Sandbox",
"eventTypes": ["employee.person.v1", "employee.assignment.status.v1"],
"url": "https://my-app.example.com/webhooks/paylocity",
"auth": {
"type": "HMAC",
"hmac": { "key1": { "expirationAt": "2027-01-01T00:00:00Z" } }
}
}'Example response: 201 Created
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Employee Updates - Sandbox",
"status": "ACTIVE",
"eventTypes": ["employee.person.v1", "employee.assignment.status.v1"],
"url": "https://my-app.example.com/webhooks/paylocity",
"auth": {
"type": "HMAC",
"hmac": {
"key1": {
"keyId": "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
"secret": "BASE64_ENCODED_SECRET",
"issuedAt": "2026-11-10T15:04:05Z",
"expirationAt": "2027-01-01T00:00:00Z"
}
}
}
}
ImportantStore the HMAC
secretimmediately. It is returned only in the response that creates the key.
Get Subscriptions [Batch]
GET /apiHub/webhooks/v1/subscriptions
Returns the webhook subscriptions configured for the authenticated client. Use it to review all of your configurations, for example when auditing which event types go to which callback URLs.
| Query parameter | Description |
|---|---|
limit | Maximum number of subscriptions to return. Default and maximum: 100 |
offset | Number of subscriptions to skip. Default: 0 |
filter | Filter expression. Filterable fields: status (eq), clientId (eq, ne, in), applicationId (eq). Example: status eq 'ACTIVE' |
sort | Comma-separated list of fields to sort by |
includeTotalCount | When true, returns the total number of matching subscriptions in the X-Pcty-Total-Count response header. Default: false |
An application can have multiple subscriptions, max is 50 per application. Each subscription can include different event types and deliver to a different URL. The same event type can be in more than one subscription. For example:
| Subscription | Event types | URL |
|---|---|---|
| HR sync | employee.person.v1 and the employee.assignment.* event types | https://my-app.example.com/hr |
| Time sync | employee.workedshift.v1, employee.paytypetransaction.v1 | https://my-app.example.com/time |
Get Subscription [Single]
GET /apiHub/webhooks/v1/subscriptions/{id}
Returns one subscription by its id (UUID). The record contains the same properties as the batch endpoint. Use it when you know the subscription ID, for example to confirm its status after a delivery issue.
Additional InformationThese endpoints return subscription configuration. They do not return webhook payloads. To see delivered events, use Events.
Update a subscription
PATCH /apiHub/webhooks/v1/subscriptions/{id}
Updates use JSON Patch (Content-Type: application/json-patch+json). The request body is an array of operations.
Supported operations
path | op | value |
|---|---|---|
/name | replace | string |
/url | replace | string |
/eventTypes | replace | array of event type strings (replaces the full list) |
/status | replace | ACTIVE or DISABLED |
/auth | replace | authentication object (replaces the full configuration) |
/auth/hmac/key1, /auth/hmac/key2 | add | object with expirationAt (creates the key) |
/auth/hmac/key1/expirationAt, /auth/hmac/key2/expirationAt | replace | ISO 8601 date-time |
Rules:
- Only
replaceandaddare supported.remove,move,copy, andtestare not. - Each
pathcan appear only once per request. valueis required and cannot be empty.- To add or remove one event type,
replace/eventTypeswith the full new list.
Example: change the URL and event types
curl -X PATCH "https://dc1demogwext.paylocity.com/apiHub/webhooks/v1/subscriptions/YOUR_SUBSCRIPTION_ID" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json-patch+json" \
-d '[
{ "op": "replace", "path": "/url", "value": "https://my-app.example.com/webhooks/v2" },
{ "op": "replace", "path": "/eventTypes", "value": [
"employee.person.v1",
"employee.assignment.v1",
"employee.assignment.payrate.v1"
] }
]'Example: pause and resume delivery
[ { "op": "replace", "path": "/status", "value": "DISABLED" } ][ { "op": "replace", "path": "/status", "value": "ACTIVE" } ]Responses
| Status | When |
|---|---|
200 OK | The update changed authentication settings. The response contains the resulting HMAC key details, including the secret of any newly created key. |
204 No Content | The update did not change authentication settings. |
Changes apply to future deliveries only. For key rotation, see Webhooks Authentication.
Events that happen while a subscription is DISABLED are not queued, no events will be delivered when it is set back to ACTIVE for that time it was disabled.
Delete a subscription
DELETE /apiHub/webhooks/v1/subscriptions/{id}
Deletes the subscription and stops event notifications to its URL. A successful request returns 204 No Content.
To stop delivery temporarily without deleting the subscription, set /status to DISABLED instead.
Subscription statuses
The API returns one of the following values in status:
| Status | Meaning | What to do |
|---|---|---|
ACTIVE | Events are being delivered | No action |
DISABLED | Delivery is paused. Set by you with PATCH /status. | Set /status to ACTIVE to resume. |
UNREACHABLE | Deliveries failed for about 24 hours because the endpoint could not be reached. Delivery is stopped. | To recover, fix your endpoint and PATCH subscription status back to ACTIVE. Review missed events with the Events endpoints. |
Errors
| Status | Likely cause |
|---|---|
400 | Invalid request body, invalid URL, unsupported patch operation, or expiration date not in the future |
401 | Missing or expired access token |
403 | Application does not have Webhooks API access or access to a requested event type |
404 | Subscription not found |
500 | Unexpected Paylocity error. Error responses include an errorId to share with support. |