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/management/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

For details on which fields trigger each webhook, see our SDK here!

***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!
   
• 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.  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 by using the notificationId. 
   
• Notification body will not give the details as to what has changed, but that the fact there was a change in that field/domain.
   
• 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!