Planning your integration with Paychex webhooks

An event-driven approach ensures you can send the right notification to the right application closest to when it occurs.  When you subscribe to our webhooks for your integration, you will receive update messages every time that an element is created, updated or deleted. You won’t need to send recurring requests to poll for updates!  

There are several 'plumbing' details that need attention before you can start receiving webhook events in your event driven application. As described in 'Our Process' tab, (Chose the process if your a 3rd party/partner or a client) you will need to create a app with us, obtain access, and develop a web app that consumes webhook events. Whether your a Paychex client or a 3rd party, you can now register without contacting support by using this step, by step guide!

Lets Get Started!

1. Look over our topics (domains)

As a developer, you will “register” to certain actions and tell us where to send notifications.   Once your app has been created, and before you register for webhooks please take a look at the webhook domains we offer,  which will show you which data fields will trigger a notification to the client or clients who are subscribed. 

2. Register for what you need!

Once you have your app ready, and you know which domains you would like,  you need to develop, deploy and host a web app that will receive Paychex webhook events in our non-prod environment.  Your app needs to subscribe to a topic (AKA 'domains') and the webhook subscription sends a webhook to an endpoint url. 
IMPORTANT! Also please be aware and accommodate for the fact that If Paychex receives anything but a 2XX response, we will queue and re-try every 5 minutes, until success! We may have to reach out to you and disable your queue if this occurs! 
 

Registration - Step 1: Authenticate and Secure: Paychex Webhook-based APIs provide four methods for confirming the security of your Webhook server:

BASIC_AUTH - Provide a user name and password when making a request
APIKEY -Static key needs to be included in the header of each request
OAUTH2 - Putting your apps client id and client secret as query parameters to acquire a token for Webhook POST request
OAUTH2_BASIC - Putting your apps client id and client secret in the Authorization header as a base64 encoded representation to acquire a token for Webhook POST request
 

Registration - Step 2: Using  GET /management/domains - after you authenticate, you can get a list of domains that you can register for. Pick the domain enum(s) desired for your post action. You can add multiple domains at once as a string separated by a comma.

Registration Step - 3: Then do a POST/management/hooks-  This is your registration action! You can register with NO clientID (Which will send notifications to ALL linked clients in the app) or you can POST with a specific clientID, so then just that specific client will get the notifications you register for. 

Also in your POST you have to provide a valid url.  This is the URL to use as your webhook to receive events!

• The URI path is completely up to you. This example would be valid: https://mydomain.com/service/listen
• If you are listening for webhooks from a variety of sources, a common pattern is: https://xxxxxxxx
• The specified URL can NOT include a port specification (https://mydomain.com:5000/NoWorkie).
• We DO NOT accept free NGROK server domains, as NGROK is typically abused by malicious actors to bypass firewall restrictions.
• Make sure your domain is accessible from the internet. Please let us know if making this endpoint available to the internet is not an option.

De-Registration - Step4 : (as needed) DELETE/hooks/{hookId} - By entering the hookID, you can unsubscribe to any notification(s) you registered for previously in steps 1-2. 

3. Maintaining Webhooks

We have added a few endpoints to help in maintain your subscription. **Please note***, if you no longer are using the URL you initially provided or no longer have a need for the Webhooks you registered for, please use DELETE to unregister to avoid any support escalations.  Here are the maintenance endpoints:

• Fetch all the hooks registered for a given application 
• Fetch a unique hook registered for a given application
• Un-register (DELETE) a hook by single ID for what you no longer need

Use Cases per Domain

Webhook Topics at Paychex (also known as  'Domains' ).  Here are some of our currently available and most common use cases with Paychex integrations and the domains associated to that use case! 

WORKER USE CASES

"I need to know when employees change their name, address and phone etc." - Use  the 'WRKR_DEM' domain. One of our most common notifications! Allows the listener to know when a workers demographic data has changed (such as last name).

"I need to know when an employee's workers pay info has changed" - Use 'WRKR_CMP' - Allows the listener to know when a workers pay or salary has changed.

"I need to know when an employee's status has changed so we can react to any changes for an employee (salary, name, email, etc) -  Use 'WRKR_EMPL' , another common notification! Allows the listener to know when a workers employment status has changed (ex. the worker was in progress, now they are active, or they were active and are now terminated etc.)

"I need to know when an employee is added in Paychex, so we can take action and complete their information" -Use 'WRKR_ADD' Mostly used for onboarding purposes. This will send a notification when a new IN PROGRESS worker was added via our POST worker API or in the Paychex Flex app., so you know when to take further action on that new employee and make them 'ACTIVE' in the system.

 "I need to know when an employee's Work State has changed" -  Use 'WRKR_TAX'.  This domain is used for SUI (State Unemployment Insurance) use cases. If a worker changes the state that work in our CA system, then the 'WorkState' will change on that worker.

"I need to know if an employees' direct deposit bank account has changed" - Use 'NET_PAY_DSTRB' which allows the listener to know when something has changed on the worker that effects Net Pay (New bank routing number, change to 401k %'s etc.)

"I need to know if an employee has changed their job assignment" - Use 'WRKR_ASGN' which allows the listener to know when a worker has changed to their position or the worker's Supervisor was changed. 

COMPANY USE CASES

"I need to know when a company removed a product that is needed for the integration, so I can take action" Use - 'CLT_PROD'. NOTE: This domain is of use to partners/3rd parties only. If you are a client or have been provided a client test app, you may not see this domain! The main goal of this notification is for when a 3rd party needs to know when a client no longer has a product that is needed for the integration so that 3rd party can take additional action.

 "I need to know when a company in my integration has changed some piece of demographic data, such as their address" Use - 'CLT_DEM' which allows the listener to know when a client's demographic data has changed (Legal name, legal address etc.) and can take certain action based on that change.

 "I need to know when a company has changed their org unit" - Use 'CLT_ORG'

 "I want to be notified when our app is accepted by an employer so we can notify them to finish the onboarding" or "I want to know when companies that linked to our integration, those who have denied access to the integration so I can take action" -  Use 'CLT_ACCESS'. NOTE: This domain is of use to partners/3rd parties only. In Paychex Flex, in Company Settings, a Super Admin or a Security Admin type user can navigate to the app integration and toggle on/off their participation in the integration. The listener of this domain will get notifications of those changed actions.

"I want to know when my the companies that I linked to my app, have completed their payroll processing and paid employees." Or "as a partner app, be notified when an employer finishes a payrun so we can process the transfers for every deduction included" Use - 'CLT_PYRN' Allows the listener to know when a client's payrun has completed processing.

***Important Notes/Best Practices***

• We suggest that you asynchronously queue your messages! This is very important in case of a delay, we can eliminate bottlenecks that could overwhelm your system or ours!
   
• In some cases, your webhook may receive duplicate events that originated with a single change within Paychex. Your webhook handler should be tolerant of this and dedupe these. To find duplicates, you can look within the header key “x-payx-txid” (they will be the same ID that is repeated) that is sent across several webhook messages.
   
• Notification body will not give the details as to what has changed, but that the fact there was a change in that field/domain.
   
• Note that every webhook notification message includes a unique 'NotificationID' . the notificationId should be provided as a value for the 'x-payx-sid' on all requests deriving from the webhook.
   
• If Paychex receives anything but a 2XX response, we will queue and re-try every 5 minutes, until success. 

NOTE: If you are blocking inbound traffic and want to use webhooks you may need to allow specific Paychex IPs as follows:

PRODUCTION IP's:

• 141.123.123.196 (WDC)
• 141.123.223.196 (HDC)
• 141.123.64.72 (ODC)

NON_PROD IP's -(Such as your N1 app):

• 141.123.55.196

For any question or support, please use the 'Support' tab and contact us!