Pay Period Webhooks Overview

Pay Period Webhooks

Overview: These webhooks represent changes to a payroll pay period within the Rollfi system. They indicate when a pay period is created, submitted, processed, or finalized as part of payroll execution.

🔹 Pay Period Status Webhook

Events

payperiod.payperiodstatus.insert — emitted when a pay period is first created. The payload returns PayPeriodStatus of new, confirming the pay period was saved successfully.
payperiod.payperiodstatus.update — emitted whenever the status of an existing pay period changes.

Statuses

The PayPeriodStatus field reflects the current state of the pay period within the Rollfi system.

Status	Description
`new`	Created but not yet submitted. Edits can still be made.
`submitted`	Submitted to Rollfi but not yet processing. To make edits, the pay period may be moved to `cancelled`.
`cancelled`	Previously submitted and cancelled to allow edits before resubmission.
`inProcess`	Payroll is actively processing. Edits are no longer allowed.
`processed`	Payroll processing is complete and funds have been submitted for disbursement.
`failed`	Payroll failed due to a processing error and can be corrected and resubmitted.
`returned`	Funds were returned after processing.
`skipped`	Payroll was skipped in the system.

Note: For a detailed walkthrough of payroll submission, editing, and processing rules, see the payroll processing guide.

Example Payload

{
  "trigger": {
    "eventId": "5fd45e70-0676-419e-ba44-91f23cb71da9",
    "eventType": "payperiod.payperiodstatus.update",
    "eventTimeStamp": "04/06/2026 22:07:04"
  },
  "payload": [
    {
      "payPeriod": [
        {
          "payPeriodId": "30AF9044-3E27-4D01-9938-DAA958C88D8D",
          "payPeriod": "09/01/2025 - 09/30/2025",
          "deadLineToRunPayroll": "2025-09-26",
          "PayPeriodStatus": "submitted",
          "total": 3120.0,
          "debitAmount": 678.29,
          "employeeTaxSum": 393.4,
          "employerTaxSum": 284.89,
          "isProcessed": false,
          "payDate": "2025-09-30",
          "payBeginDate": "2025-09-01",
          "payEndDate": "2025-09-30",

          "workerType": { "workerType": "W2" },
          "payPeriodType": { "payPeriodType": "Regular" },

          "payrollLineItems": [
            {
              "userName": "John Ober",
              "grossTotal": 1900.0,
              "netTotal": 1611.59,
              "payHours": 16.0,
              "payRate": 100.0,

              "employeeTax": {
                "total": 288.41,
                "details": [
                  { "name": "Medicare", "amount": 27.55 },
                  { "name": "Social Security", "amount": 117.8 },
                  { "name": "Federal Income Tax", "amount": 143.06 }
                ]
              },

              "employerTax": {
                "details": [
                  { "name": "Unemployment Tax", "amount": 11.4 },
                  { "name": "Medicare", "amount": 27.55 },
                  { "name": "Social Security", "amount": 117.8 }
                ]
              },

              "overtime": [
                {
                  "type": "Standard Overtime",
                  "hours": 2.0,
                  "amount": 300.0
                }
              ],

              "payMethod": "Check"
            },

            {
              "userName": "Ben Fineman",
              "grossTotal": 2220.0,
              "netTotal": 2115.01,
              "payHours": 90.0,
              "payRate": 20.0,

              "employeeTax": {
                "total": 104.99,
                "details": [
                  { "name": "Medicare", "amount": 14.79 },
                  { "name": "Social Security", "amount": 63.24 },
                  { "name": "NY State Income Tax", "amount": 16.13 }
                ]
              },

              "employerTax": {
                "details": [
                  { "name": "Unemployment Tax", "amount": 6.12 },
                  { "name": "Medicare", "amount": 14.79 },
                  { "name": "Social Security", "amount": 63.24 }
                ]
              },

              "adjustments": {
                "additionalCompensation": 100.0,
                "deductions": 1000.0,
                "reimbursements": 1000.0
              },

              "overtime": [
                {
                  "type": "Holiday/Weekend OT",
                  "hours": 3.0,
                  "amount": 15.0
                }
              ],

              "payMethod": "Check"
            }
          ],

          "companyId": "EB45E206-5E50-4079-8B41-04C05E4C5338"
        }
      ]
    }
  ]
}

​Pay Period Webhooks

​🔹 Pay Period Status Webhook

​Events

​Statuses

​Example Payload

Pay Period Webhooks

🔹 Pay Period Status Webhook

Events

Statuses

Example Payload