Skip to main content

​
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.
StatusDescription
kyc not initiatedThe employee has been created and KYC has not yet been initiated. This status is returned by the insert webhook
pendingKYC is currently being processed by the verification provider.
passedKYC verification has passed. This status is required before an employee’s status in the Rollfi system can progress to Active.
failedKYC 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": "[email protected]",
          "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.
StatusDescription
Add WageThe employee has been created but does not yet have wage information. No platform invite has been sent.
Invite SentThe employee has been invited to join the platform and complete the remaining information required to activate payroll.
ActiveEmployee KYC information, wages, and bank account details (if applicable) have been added, and the employee is ready for payroll.
InActiveThe employee has been deactivated for a period of time and can be reactivated using the activateUser API.
TerminatedThe employee has been terminated and can no longer be reactivated.

​
Example Payload

{
  "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": "[email protected]",
          "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": []
        }
      ]
    }
  ]
}