---
title: "Create Subscription"
method: POST
path: "/apiHub/webhooks/v1/subscriptions"
tags: ["Subscriptions"]
---

# Create Subscription

`POST /apiHub/webhooks/v1/subscriptions`

## Request

- Base URL: `dc1demogwext.paylocity.com` (relative, and the document’s source URL is not known)
- URL: `dc1demogwext.paylocity.com/apiHub/webhooks/v1/subscriptions`
- Auth: HTTP bearer

> 🚧 Early Access API Version
> This endpoint version is currently in Early Access and available only to approved early adoption (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.

**Summary Description**

Creates a new webhook subscription, allowing clients to receive real-time event notifications from the Paylocity platform. Clients specify the event types they want to subscribe to and provide a secure endpoint URL to which Paylocity will send event payloads. Webhook subscriptions created through this endpoint allow external systems to stay in sync with changes to employee data, assignments, compensation, and more.

## Headers

- `Authorization` string, required

## Request body

- CreateSubscriptionV1Model
  - `name` string, required: The name of the subscription
  - `eventTypes` string[], required: List of 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`.
  - `auth` CreateAuthV1Model: ### Authentication Configuration Exactly one authentication object must be provided, based on the value of the `type` field: - **HMAC authentication** – populate the `hmac` object. _Future authentication protocols may introduce additional mutually exclusive objects._
    - `type` string, required: Specifies the authentication type. Allowed values are **HMAC**. This determines which authentication object (`hmac`) is populated.
    - `hmac` CreateHmacAuthV1Model
      - `key1` CreateHmacKeyV1Model, required
        - `expirationAt` string, date-time, required: The date and time when the HMAC key will expire
  - `url` string, required: The HTTPS URL where webhook events will be delivered

## Response `201`

Created

- CreateSubscriptionV1Response
  - `id` string, uuid: The unique identifier of the webhook subscription.
  - `name` string, nullable: The name of the webhook subscription.
  - `status` string, nullable: The current status of the webhook subscription. Allowable Values: ACTIVE, DISABLED, DEACTIVATED, UNREACHABLE, PENDING_VERIFICATION.
  - `eventTypes` string[], nullable: List of event types the subscription receives (e.g. `employee.person.v1`, `employee.assignment.v1`).
  - `url` string, nullable: The URL where webhook events are delivered.
  - `auth` CreateSubscriptionAuthV1Response
    - `type` string, nullable: The authentication type configured for the subscription. Allowable Values: HMAC.
    - `hmac` CreateSubscriptionHmacAuthV1Response
      - `key1` CreateSubscriptionHmacKeyV1Response
        - `keyId` string, uuid, nullable: The unique identifier of the HMAC key.
        - `secret` string, nullable: The HMAC secret used to sign webhook deliveries. Returned only in the response that creates the key.
        - `issuedAt` string, date-time, nullable: The date and time the HMAC key was issued.
        - `expirationAt` string, date-time, nullable: The date and time the HMAC key expires.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error

---

[API](https://skmtc.dev/paylocity/apis/webhooks-api.md) - [All operations](https://skmtc.dev/paylocity/apis/webhooks-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paylocity/apis/webhooks-api/revisions/4206e9534cc6?raw)