Subscriptions

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 Information

Selecting 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].

PropertyTypeDescription
idstring (UUID)Unique identifier of the subscription. Generated by Paylocity.
clientIdstring (UUID)The ID of the API credentials that own the subscription
applicationIdstring (UUID)The ID of the application associated with the API credentials
namestringName of the subscription, such as Employee Updates - Production
statusstringCurrent status. See Subscription statuses.
eventTypesarray of stringsEvent types delivered to this subscription
urlstringURL where events are delivered
auth.typestringDelivery signing type. Allowable value: HMAC
auth.hmac.key1objectPrimary HMAC key: keyId (UUID), issuedAt, expirationAt
auth.hmac.key2objectSecondary HMAC key, used for key rotation: keyId (UUID), issuedAt, expirationAt. Present only when a second key exists.
createdAtstring (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

PropertyRequiredTypeDescription
nameYesstring (max 100 characters)Name of the subscription
eventTypesYesarray of stringsEvent 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
urlYesstringThe HTTPS URL where events will be delivered
authRecommendedobjectHMAC 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"
      }
    }
  }
}
❗️

Important

Store the HMAC secret immediately. 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 parameterDescription
limitMaximum number of subscriptions to return. Default and maximum: 100
offsetNumber of subscriptions to skip. Default: 0
filterFilter expression. Filterable fields: status (eq), clientId (eq, ne, in), applicationId (eq). Example: status eq 'ACTIVE'
sortComma-separated list of fields to sort by
includeTotalCountWhen 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:

SubscriptionEvent typesURL
HR syncemployee.person.v1 and the employee.assignment.* event typeshttps://my-app.example.com/hr
Time syncemployee.workedshift.v1, employee.paytypetransaction.v1https://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 Information

These 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

pathopvalue
/namereplacestring
/urlreplacestring
/eventTypesreplacearray of event type strings (replaces the full list)
/statusreplaceACTIVE or DISABLED
/authreplaceauthentication object (replaces the full configuration)
/auth/hmac/key1, /auth/hmac/key2addobject with expirationAt (creates the key)
/auth/hmac/key1/expirationAt, /auth/hmac/key2/expirationAtreplaceISO 8601 date-time

Rules:

  • Only replace and add are supported. remove, move, copy, and test are not.
  • Each path can appear only once per request.
  • value is required and cannot be empty.
  • To add or remove one event type, replace /eventTypes with 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

StatusWhen
200 OKThe update changed authentication settings. The response contains the resulting HMAC key details, including the secret of any newly created key.
204 No ContentThe 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:

StatusMeaningWhat to do
ACTIVEEvents are being deliveredNo action
DISABLEDDelivery is paused. Set by you with PATCH /status.Set /status to ACTIVE to resume.
UNREACHABLEDeliveries 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

StatusLikely cause
400Invalid request body, invalid URL, unsupported patch operation, or expiration date not in the future
401Missing or expired access token
403Application does not have Webhooks API access or access to a requested event type
404Subscription not found
500Unexpected Paylocity error. Error responses include an errorId to share with support.