Employee Webhooks Overview

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

{
  "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.
`Deleted`	The employee was deleted during the hiring and onboarding stage, before becoming `Active`.
`Former`	The employee was added as a former employee — paid during the current year on the company’s previous payroll platform but already terminated. Former employees are required for accurate tax calculations.

Example Payload

{
  "trigger": {
    "eventId": "c68d4dc1-638a-4baa-9ccb-26a2520e38a2",
    "eventType": "employee.employeestatus.update",
    "eventTimeStamp": "01/08/2026 13:10:02"
  },
  "payload": [
    {
      "user": [
        {
          "user": "Alex Morgan",
          "userId": "A12F45BC-9D31-4C9E-B28F-7F6E2C91D4A8",
          "userReferenceId": "",
          "companyId": "8E9F2B11-6A44-4D8C-B3A2-91F6D2E8C7A0",
          "status": {
            "userStatus": "Active"
          },
          "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,
              "WageRate": 85,
              "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)"
            }
          ],
          "bankAccounts": [
            {
              "userPayAccountEntityId": "5B8E2D91-4C77-4F1A-9E3B-8D2A6C4F7E10",
              "bankName": "Chase",
              "accountName": "Alex Morgan Checking",
              "accountNumber": "XXXXXXXXX4321",
              "payPercentage": 100.0,
              "accountType": "checking",
              "status": "ready",
              "accountPriority": "Primary"
            }
          ],
          "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": "974619053",
          "userRemoteLocation": null,
          "stateW4Informations": [],
          "timeOffRequests": [],
          "employeeGarnishments": []
        }
      ]
    }
  ]
}

​Employee Webhooks

​🔹 Employee KYC Status Webhook

​Events

​Statuses

​Example Payload

​🔹 Employee Status Webhook

​Events

​Statuses

​Example Payload

Employee Webhooks

🔹 Employee KYC Status Webhook

Events

Statuses

Example Payload

🔹 Employee Status Webhook

Events

Statuses

Example Payload