Webhooks for payroll

A common use case for integrating with a payroll API is to stay informed whenever a connected company runs payroll or adds or updates an employee record.

Running a regularly scheduled job to sync data from QuickBooks Payroll to your platform can be time-consuming and expensive. Instead, we strongly recommend using webhooks. Webhooks provide event-triggered callbacks for the entities your app needs to track. They automatically notify you whenever data changes in your end-user’s QuickBooks Payroll company files.

Webhooks apply to all QuickBooks Payroll companies connected to your app.

To use webhooks, you need to configure an endpoint that our servers can call. Once webhooks are active, we’ll send the requested event data, changes, and notifications to that endpoint.

For example, you can be notified whenever a payslip is created. When a user in a connected QuickBooks Payroll company runs payroll and generates payslips, you will receive one webhooks notification for each created payslip. The notification will contain the payslip ID. You can then use our API to pass those IDs as filters to retrieve the payslip record data.

Webhooks are available for two payroll entities: Payslips and PayrollEmployee. If your app is using the payroll scopes, you will see these two entities listed in your developer portal under webhooks.

To configure webhooks for payroll:

1. Sign in to your developer account.
2. Select My Hub > App dashboard from the upper-right corner of the toolbar.
3. Select and open the app you want to subscribe.
4. From the left navigation pane, select Webhooks.
5. Select Production.
6. Enter the endpoint URL. This is where the server will send notifications.
7. Select the entities (PayrollEmployee and/or Payslip) and operations you want to receive notifications for. You can send test notifications from the Actions dropdown.

x

8. Select Save.

Detailed instructions on how to set up webhooks are available here.

When you receive a webhooks notification, ensure you respond promptly. If your endpoint doesn’t respond with an HTTP status code 200 within three seconds, the transaction will time out and retry. Don’t process the notification payload or perform complex operations within the webhooks endpoint implementation. Do the processing on a separate thread asynchronously using a queue.

You can review more best practices for webhooks here.