> ## 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.

# Employee Webhooks

## Employee Webhooks

* **Overview:** These webhooks represent changes in an employee’s verification and lifecycle state within the platform, from identity verification through payroll readiness and employment changes.

***

## 🔹 Employee KYC Status Webhook

### Events

* `employee.kycstatus.insert` — emitted when an employee record is first created. The payload returns the initial kycStatus of `kyc not initiated`, confirming the employee was saved successfully.
* `employee.kycstatus.update` — emitted whenever an employee’s KYC verification status changes after creation.

### Statuses

The kycStatus field indicates the current identity verification state of the employee.

| Status              | Description                                                                                                                         |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `kyc not initiated` | The employee has been created and KYC has not yet been initiated. This status is returned by the insert webhook                     |
| `pending`           | KYC is currently being processed by the verification provider.                                                                      |
| `passed`            | KYC verification has passed. **This status is required before an employee’s status in the Rollfi system can progress to `Active`.** |
| `failed`            | KYC verification has failed and requires follow-up.                                                                                 |

### Example Payload

```json theme={null}
{
  "trigger": {
    "eventId": "6f91c2a4-8d31-4a1b-b5f4-91a2d7c4e810",
    "eventType": "employee.kycstatus.update",
    "eventTimeStamp": "01/07/2026 15:27:12"
  },
  "payload": [
    {
      "user": [
        {
          "user": "Alex Morgan",
          "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8",
          "userReferenceId": "",
          "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0",
          "status": {
            "userStatus": "Invite Sent"
          },
          "WorkerType": {
            "WorkerType": "W2"
          },
          "firstName": "Alex",
          "lastName": "Morgan",
          "middleName": "",
          "phoneNumber": "5551234567",
          "kycStatus": "passed",
          "jobTitle": "Quality Analyst",
          "dateOfJoin": "2026-01-07",
          "email": "alex.morgan@example.com",
          "userWages": [
            {
              "userWageId": "E4D92C17-1B55-4C3E-A9D8-2F5B9A1C7E44",
              "standardWorkingHours": 0.0,
              "WageRate": 85.0,
              "WageBasis": {
                "WageBasis": "Per Month"
              },
              "paymentMethod": {
                "PaymentMethod": "Check"
              }
            }
          ],
          "bankAccounts": []
        }
      ]
    }
  ]
}
```

***

## 🔹 Employee Status Webhook

### Events

* `employee.employeestatus.insert` — emitted when an employee record is first created. The payload returns userStatus of `Add Wage`, confirming the employee was saved successfully.
* `employee.employeestatus.update` — emitted whenever an employee’s status in the Rollfi system changes after creation.

### Statuses

The `userStatus` field reflects the employee’s current status in the Rollfi system.

| Status        | Description                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Add Wage`    | The employee has been created but does not yet have wage information. No platform invite has been sent.                           |
| `Invite Sent` | The employee has been invited to join the platform and complete the remaining information required to activate payroll.           |
| `Active`      | Employee KYC information, wages, and bank account details (if applicable) have been added, and the employee is ready for payroll. |
| `Deactivate`  | The employee has been deactivated for a period of time and can be reactivated using the `activateUser` API.                       |
| `Terminated`  | The employee has been terminated and can no longer be reactivated.                                                                |

### Example Payload

```json theme={null}
{
  "trigger": {
    "eventId": "ce5beb7f-93b4-4f3f-bef6-9ce3bd4e574f",
    "eventType": "employee.employeestatus.update",
    "eventTimeStamp": "01/08/2026 12:21:54"
  },
  "payload": [
    {
      "user": [
        {
          "user": "Wfourtesttwo Testtt",
          "userId": "8CA6403C-4667-4B0C-BBB8-929CA0D62350",
          "userReferenceId": "",
          "companyId": "46F9528D-2E48-446A-903F-CFADBE0D08F4",
          "status": {
            "userStatus": "Invite Sent"
          },
          "WorkerType": {
            "WorkerType": "W2"
          },
          "firstName": "Wfourtesttwo",
          "lastName": "Testtt",
          "middleName": "",
          "phoneNumber": "5636525874",
          "kycStatus": "kyc not initiated",
          "jobTitle": "HR",
          "dateOfJoin": "2026-01-07",
          "email": "Wfourtesttwo@mailsac.com",
          "userWages": [
            {
              "userWageId": "E874BFF0-0D4F-492C-96CD-36808187749C",
              "standardWorkingHours": 0.0,
              "WageRate": 1500.0,
              "WageBasis": {
                "WageBasis": "Per Month"
              },
              "paymentMethod": {
                "PaymentMethod": "Direct Deposit"
              },
              "employeeRefTaxExempt": "No, this employee is not tax exempt",
              "employeeType": "Salary/Eligible for overtime",
              "differentialPay": null,
              "employmentStatus": "Full Time (30+ Hours per week)"
            }
          ],
          "userRemoteLocations": [],
          "companyLocationCategory": {
            "companyLocationCategory": "Office"
          },
          "companyLocation": {
            "companyLocation": "Primary Residence",
            "companyLocationId": "746398E0-B335-47C6-BF78-D268D034594E",
            "Address1": "6875 Sand Lake Rd",
            "Address2": "",
            "City": "Orlando",
            "Country": "US",
            "State": "FL",
            "Zipcode": "32819"
          },
          "stateCode": null,
          "W4Informations": [],
          "ssn": null,
          "userRemoteLocation": null,
          "stateW4Informations": [],
          "bankAccounts": [],
          "timeOffRequests": [],
          "employeeGarnishments": []
        }
      ]
    }
  ]
}
```