A subscription ties a set of event types to a delivery URL and an authentication configuration. This page walks through creating and managing subscriptions.

Step 1: Create a Subscription

POST /apiHub/webhooks/v1/subscriptions

curl --location --request POST 'https://gwext.paylocity.com/apiHub/webhooks/v1/subscriptions' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Employee Updates - HMAC",
  "eventTypes": ["employee.person.v1", "employee.assignment.v1"],
  "url": "https://my-app.example.com/webhooks/paylocity",
  "auth": {
    "type": "HMAC",
    "hmac": {
      "key1": { "expirationAt": "2027-01-01T00:00:00Z" }
    }
  }
}'

A successful call returns 201 Created with the subscription id, status, and (for HMAC) the one-time secret — see Webhooks-Authentication for why you should capture it immediately.

Managing Subscriptions

List subscriptions

GET /apiHub/webhooks/v1/subscriptions

Supports filter (status eq, clientId eq/ne/in, applicationId eq), and limit (default/max 100).

curl --location 'https://gwext.paylocity.com/apiHub/webhooks/v1/subscriptions?filter=status eq %27Active%27&limit=25' \
--header 'Authorization: Bearer <token>'

Read a single subscription

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

Update a subscription

PATCH /apiHub/webhooks/v1/subscriptions/{id} accepts a JSON Patch document (application/json-patch+json). Common operations:

Change the delivery URL

{ "operations": [{ "op": "replace", "path": "/url", "value": "https://new-endpoint.example.com/webhooks" }] }

Change subscribed event types

{ "operations": [{ "op": "replace", "path": "/eventTypes", "value": ["employee.person.v1", "employee.assignment.v1", "employee.assignment.payrate.v1"] }] }

Pause delivery (set the subscription to Inactive without deleting it)

{ "operations": [{ "op": "replace", "path": "/status", "value": "Inactive" }] }

See Webhooks-Authentication for rotating HMAC keys via PATCH.

Delete a subscription

DELETE /apiHub/webhooks/v1/subscriptions/{id} — permanently removes the subscription. No further events will be delivered to it.

Errors

Managing Webhook Subscriptions

A webhook subscription tells Paylocity which event types to send and where to send them.

Use the Subscriptions API to:

• Create a subscription
• View existing subscriptions
• Update a subscription
• Pause or resume webhook delivery
• Delete a subscription

Before creating a subscription, make sure you have selected the event types you want to receive and have an endpoint ready to receive webhook deliveries.

Create a Subscription

POST /apiHub/webhooks/v1/subscriptions

To create a subscription, provide a name, the event types you want to receive, your delivery URL, and the authentication configuration for the subscription.

Example request

curl --location --request POST 'https://gwext.paylocity.com/apiHub/webhooks/v1/subscriptions' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Employee Updates - HMAC",
  "eventTypes": ["employee.person.v1", "employee.assignment.v1"],
  "url": "https://my-app.example.com/webhooks/paylocity",
  "auth": {
    "type": "HMAC",
    "hmac": {
      "key1": { "expirationAt": "2027-01-01T00:00:00Z" }
    }
  }
}'

A successful request returns 201 Created and the newly created subscription.

For details about the HMAC secret returned when the subscription is created, see Webhooks-Authentication

View Subscriptions

You can retrieve all available subscriptions or retrieve a specific subscription by its id.

List subscriptions

GET /apiHub/webhooks/v1/subscriptions

Use this endpoint to retrieve your subscriptions.

You can narrow the results using:

• filter
  • status eq, clientId eq/ne/in, applicationId eq
• limit
  • Default: 100, Maximum: 100

Example

curl --location 'https://gwext.paylocity.com/apiHub/webhooks/v1/subscriptions?filter=status eq %27Active%27&limit=25' \
--header 'Authorization: Bearer <token>'

Get a Subscription by ID

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

Use this endpoint when you already know the subscription id and want to retrieve that specific subscription.

Update a Subscription

PATCH /apiHub/webhooks/v1/subscriptions/{id}

Use this endpoint to change an existing subscription without creating a new one.

Updates are submitted as a JSON Patch document using:

Content-Type: application/json-patch+json

Common updates include changing the delivery URL, changing the subscribed event types, or changing the subscription status.

Change the Delivery URL

Replace the subscription's url when webhook deliveries need to be sent to a different endpoint.

{ "operations": [{ "op": "replace", "path": "/url", "value": "https://new-endpoint.example.com/webhooks" }] }

Change Event Types

Replace eventTypes when you need to change which events the subscription receives.

{ "operations": [{ "op": "replace", "path": "/eventTypes", "value": ["employee.person.v1", "employee.assignment.v1", "employee.assignment.payrate.v1"] }] }

See Webhook Event Types for available event types.

Pause Delivery

You can temporarily stop deliveries without deleting the subscription by changing its status to Inactive.

{ "operations": [{ "op": "replace", "path": "/status", "value": "Inactive" }] }

Because the subscription still exists, it can be updated again later rather than recreated.

For HMAC key rotation, see Webhooks-Authentication.

Delete a Subscription

DELETE /apiHub/webhooks/v1/subscriptions/{id}

Use this endpoint when the subscription is no longer needed.

Deleting a subscription permanently removes it, and Paylocity will no longer deliver events to that subscription.

Pause vs. delete

Set a subscription to Inactive when you only need to temporarily stop webhook deliveries.

Delete the subscription when it is no longer needed and should be permanently removed.

Common Errors

The following errors may occur when creating or managing subscriptions: