​

Async Payroll Imports and Pay Schedule Webhooks

​

Highlights

• Asynchronous payroll import: importRegularPayrollData and importDifferentialPayrollData now validate immediately and process accepted imports in the background.
• Pay schedule webhooks: New events notify your systems when pay schedules are created or their status changes.
• $0 wage rate support: Payroll import and wage workflows now support employee wage rates of $0 where applicable.

​

New Features

​

🔹 Asynchronous payroll imports

• After request validation succeeds, the API returns a Pending response and continues applying payroll changes in the background instead of holding the request open until every payroll mutation finishes.
• During that import window, getPayPeriodDetails returns a 400 response so clients do not display stale payroll data while the import is still being applied.
• When the import finishes, Rollfi sends the payperiod.payperiodstatus.update webhook. That update does not introduce a new completion status. Instead, it restores the pay period to the same status you observed before the import began, while signaling that background import processing has completed.
  • For example, if the pay period was new before the import started, the completion webhook will surface that pay period as new again. If it was cancelled before the import started, the completion webhook will surface cancelled again. In other words, the return to the prior visible pay period status is the signal that the async import window has closed and it is safe to re-fetch payroll details.
• When some employee-level mutations fail during async processing, the same payperiod.payperiodstatus.update webhook can include a top-level error object summarizing those failures.

{
    "trigger": {
        "eventId": "f1d8f4a9-8b6a-4de4-a07d-0f7c4f17b0e2",
        "eventType": "payperiod.payperiodstatus.update",
        "eventTimeStamp": "07/20/2026 14:37:11"
    },
    "payload": [
        // ... [PayPeriod payload omitted] ...
    ],
    "error": {
        "code": 400,
        "message": "Payroll changes not processed for 2 user(s) due to negative net pay",
        "userIds": [
            "A9275709-E4E0-476F-AE77-BD85F7BDEECD",
            "96069AD6-C3EB-476B-BD3E-E334270EEFA4"
        ]
    }
}

​

🔹 Pay schedule webhook events

• Your systems can now react automatically when pay schedules change. Two new webhook events are available:
  • payschedule.paysheduleisactive.insert — sent when a pay schedule is created.
  • payschedule.paysheduleisactive.update — sent when a pay schedule’s status changes.

​

🔹 Support for $0 wage rates

​

⚠️ Notes for Integrators

​

Recommended Next Steps

1. Update any importRegularPayrollData client flow to handle Pending responses.
2. Avoid rendering payroll details until getPayPeriodDetails succeeds after import completion.
3. Review the PaySchedule webhook overview if you build event-driven integrations that could benefit.