> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rollfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay Period Webhooks

## 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](https://developer.rollfi.xyz/api-reference/payroll/removeAdditionalCompensations).

***

### Example Payload

```json theme={null}
{
  "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"
        }
      ]
    }
  ]
}
```