Webhooks allow your application to receive real-time notifications whenever specific events occur in Paychex systems (such as record creation, updates, or deletions). Instead of polling for changes, Paychex pushes updates directly to your registered endpoint.

This guide summarizes everything you need to know to plan, register, test, and maintain your webhook integration.
 

1. Understand Webhook Domains

Before you register, review the available webhook domains. Domains describe which data fields trigger notifications, helping you decide which events your integration should listen for. 

Below is the list of Partner domains and Client domains, Click on each domain to know the fields which trigger the domains.

2. Prepare Your Application

Before subscribing to webhooks, you must:
•    Register your application with Paychex
•    Obtain access credentials
•    Build and deploy a web-accessible endpoint
•    Ensure your endpoint can receive and return 2XX HTTP responses

Important: If your endpoint returns anything other than 2XX, Paychex retries delivery every 5 minutes until successful. Persistent failures may result in your queue being temporarily disabled.

3. Authentication Options

Paychex webhooks support four authentication methods for securing your endpoint:
•    BASIC_AUTH – Username + password
•    APIKEY – Static key sent in headers
•    OAUTH2 – Client ID + secret passed as query parameters
•    OAUTH2_BASIC – Client ID + secret sent as Base64 in the Authorization header

Choose the method your system can support reliably.

4. Registering for Webhooks

Step 1 – Get Available Domains

Use the below cURL  to retrieve the list of domains you can subscribe to.

curl --location 'https://api.paychex.com/management/domains' \
--header 'Authorization: Bearer <your_bearerToken_here>' \
--data ''

Step 2 – Create Your Webhook Subscription

Use the below cURL to register a webhook

curl --location 'https://api.paychex.com/management/hooks' \
--header 'Authorization: Bearer <your_bearerToken_here>' \
--header 'Content-Type: application/json' \
--data '{
  
  "companyId": "00H2A1IUK695XL45NDO6",
  "uri": "https://5v0mw421x8.execute-api.us-east-2.amazonaws.com/n2a/messages/no-auth?hookid=CLT_PROD_N@A_TES",
  "authentication": {
    "authType": "NO_AUTH"
  },
  "domains": [
    "WRKR_CMP"
  ]
}'

Sample Response

{
    "hookId": "a9e3e787-e7ad-41df-8b77-bb59314dce8a",
    "companyId": "00H2A1IUK695XL45NDO6",
    "uri": "https://5v0mw421x8.execute-api.us-east-2.amazonaws.com/n2a/messages/no-auth?hookid=CLT_PROD_N@A_TES",
    "authType": "NO_AUTH",
    "createdDate": "2026-01-12T13:19:58.664Z",
    "active": true,
    "domains": [
        "WRKR_CMP"
    ]
}

You may register:
•    Without a clientId → all clients linked to your app receive notifications
•    With a specific clientId → only that client receives the events

While registering, you must provide a valid public URL for your webhook endpoint.

5. Managing Webhooks

Paychex provides endpoints to manage ongoing webhook registrations:
•    Fetch all hooks for an application
•    Fetch a single hook by ID
•    Remove old or unused hooks with:

curl --location --request DELETE 'https://api.paychex.com/management/hooks/{hook_id}' \
--header 'Authorization: Bearer <your_bearerToken_here>' \
--data ''

Always remove hooks you no longer use to avoid unnecessary retries or support escalations.
 

If Webhook registration fails, it may be due to an invalid or unreachable URL, or incorrect credentials when using authType as "BASIC_AUTH", "OAUTH2", "APIKEY" etc.

Below are the common error responses you may encounter:

Sample Response when URL is Invalid or Unreachable

{
    "content": [],
    "errors": [
        {
            "code": "API-100",
            "description": "Invalid webhook request.404 Not Found",
            "resolution": "null"
        }
    ],
    "links": []
}

Sample Response when Auth credentials are Incorrect

{
    "content": [],
    "errors": [
        {
            "code": "API-100",
            "description": "Invalid webhook request.401 Unauthorized",
            "resolution": "null"
        }
    ],
    "links": []
}