> ## Documentation Index
> Fetch the complete documentation index at: https://rollfi-monthly-semi-monthly.mintlify.site/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": "c25bc67f-99ff-42f2-9b00-a1fa899c233e",
    "eventType": "payperiod.payperiodstatus.update",
    "eventTimeStamp": "01/07/2026 17:30:46"
  },
  "payload": [
    {
      "payPeriod": [
        {
          "payPeriodId": "33D83855-4493-441A-894D-2C86B110C676",
          "payPeriod": "01/01/2026 - 01/31/2026",
          "deadLineToRunPayroll": "2026-01-07",
          "PayPeriodStatus": "inProcess",
          "total": 2760.00,
          "employeeTaxSum": 852.68,
          "employerTaxSum": 302.22,
          "isProcessed": false,
          "payDate": "2026-01-12",
          "payBeginDate": "2026-01-01",
          "payEndDate": "2026-01-31",
          "workerType": {
            "workerType": "W2"
          },
          "payPeriodType": {
            "payPeriodType": "Off-Cycle"
          },
          "payrollLineItems": [
            {
              "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8",
              "userName": "Alex Morgan",
              "baseTotal": 2760.00,
              "grossTotal": 2760.00,
              "netTotal": 1907.32,
              "payHours": 176.0,
              "payRate": 2760.00,
              "employeeTax": {
                "employeeTax": 852.68
              },
              "employeeTaxDetails": [
                {
                  "taxName": "Medicare",
                  "taxAmount": 40.02,
                  "displayName": "Medicare"
                },
                {
                  "taxName": "Social Security",
                  "taxAmount": 171.12,
                  "displayName": "Social Security Tax"
                },
                {
                  "taxName": "Federal Withholding Tax",
                  "taxAmount": 445.75,
                  "displayName": "Federal Income Tax"
                }
              ],
              "employerTaxDetails": [
                {
                  "taxName": "FUTA",
                  "taxAmount": 16.56
                },
                {
                  "taxName": "Medicare",
                  "taxAmount": 40.02
                },
                {
                  "taxName": "Social Security",
                  "taxAmount": 171.12
                }
              ],
              "payDetails": [
                {
                  "payPercentage": 100.0,
                  "amount": 1907.32,
                  "employeePayAccount": {
                    "accountName": "Checking •••• 0011"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```