Webhook Event Types

Check-Topic header

Each webhook request has a Check-Topic header that represents which type of API event the webhook is associated with.

Topic	Description
payroll	Any payroll lifecycle event
company_tax_document	Any company tax document event
company_authorization_document	Any company authorization document event
employee_tax_document	Any employee tax document event
contractor_tax_document	Any contractor tax document event
bank_account	Any bank account event
benefit	Any benefit event
company_benefit	Any company benefit event
post_tax_deduction	Any post-tax deduction event
company	Any company event
employee	Any employee event
contractor	Any contractor event
workplace	Any workplace event
earning_code	Any earning code event
payment	Any payment status change event
federal_ein_verification	Any federal EIN verification change event
requirement	Any Requirements API events
company_processing_status	Any company processing status change event
pay_schedule	Any pay schedule event
earning_rate	Any earning rate event
tax_filing	Any tax filing event
net_pay_split	Any net pay split event
integration_access	Any integration access event
enrollment_profile	Any enrollment profile event

Payroll Events

Event	Description
status_change	A payroll instance's status changes (for example, a payroll moves from `pending` to `processing`).
created	A payroll was created
deleted	A payroll was deleted

Example webhook event payload

{
    "event": "status_change",
    "data": {
        "id": "pay_Z26PNMC7Ky1wfFQzVqfF",
        "company": "com_sx3svU6K8c5ZkSFlOh5p",
        "period_start": "2019-06-16",
        "period_end": "2019-06-29",
        "approval_deadline": "2019-07-02T00:00:00.000000Z",
        "approved_at": "2019-06-29T18:26:56.848920Z",
        "payday": "2019-07-05",
        "status": "paid",
        "type": "regular",
        ... // remainder of payroll data
}

More detail on the Payroll object.

Document Events

These events apply to employee, company, and contractor document resources.

Event	Description
created	A document was created (For example, this could be triggered when an employee submits a document through Check Onboard)
deleted	A document was deleted

Example webhook event payload
Here is an example webhook event payload for an employee tax document:

{
    "event": "created",
    "data": {
        "id": "doc_oSFuU4veTPqG8KRGAINc", 
        "year": 2021,
        "category": "employee_tax_document",
        "label": "Federal W-4", 
        "employee": "emp_jMjjmrBTSNzBCG1kRkh9", 
        "filed_on": "2021-02-18", 
        "jurisdiction": "FED"
    }
}

More detail on the Document object (and the various document categories).

Bank Account Events

Event	Description
created	A bank account was created
updated	A bank account was updated
deleted	A bank account was deleted

Example webhook event payload

{
    "event": "created",
    "data": {
        "id": "bnk_BcuzUyfy6Rt2Woa6TAHz",
        "company": "com_cHVEOcdE6bzMiBxpOzTQ",
        "status": "ownership_verified",
        "disabled_reason": null,
        "plaid_bank_account": {
            "name": "Plaid Checking",
            "plaid_public_token": "public-sandbox-023e3f0d-bcd8-46ee-b1dd-fcb67bcb4372",
            "institution_name": "Chase",
            "mask": "0000",
            "type": "depository",
            "subtype": "checking",
            "verified": true,
            "microdeposit_verification_status": null
        }
    }
}

More detail on the Bank Account object.

Benefit Events

Event	Description
created	A benefit was created
updated	A benefit was updated
deleted	A benefit was deleted

Example webhook event payload

{
    "event": "created",
    "data": {
        "id": "ben_x3BTJJjgRCHDRTffYUAJ",
        "benefit": "401k",
        "company_benefit": null,
        "employee": "emp_SXRWvWC6TYtZLHpCYxOi",
        "description": "Retirement",
        "effective_end": null,
        "effective_start": "2021-03-26",
        "hsa_contribution_limit": null,
        "company_contribution_amount": "1.00",
        "company_contribution_percent": null,
        "employee_contribution_amount": "1.00",
        "employee_contribution_percent": null
    },
}

More detail on the Benefit object.

Company Benefit Events

Event	Description
created	A company benefit was created
updated	A company benefit was updated
deleted	A company benefit was deleted

Example webhook event payload

{
    "event": "created",
    "data": {
        "id": "cbn_lrcYUhTk1FVZl2vSCOBP",
        "benefit": "401k",
        "company": "com_kKTK4VafMNc5pIbI0G9x",
        "description": "Guideline 401(k)",
        "effective_end": null,
        "effective_start": "2021-03-26",
        "company_contribution_amount": "1.00",
        "company_contribution_percent": null,
        "employee_contribution_amount": "1.00",
        "employee_contribution_percent": null
    },
}

More detail on the The company benefit object.

Post-Tax Deduction Events

Event	Description
created	A post tax deduction was created
updated	A post tax deduction was updated
deleted	A post tax deduction was deleted

Example webhook event payload

{
    "event": "created",
    "data": {
        "id": "ptd_g4AGCxtz8VakIL4PmZ0r",
        "type": "miscellaneous",
        "employee": "emp_bvNhcPxrbvRqgyCrlUcj",
        "description": "Union dues",
        "effective_start": "2020-01-01",
        "effective_end": null,
        "miscellaneous": {
            "amount": "10.00",
            "percent": null,
            "total_amount": "50.00"
        }
    }
}

More detail on the Post-Tax Deduction object.

Company Events

Event	Description
created	A company was created
updated	A company was updated
terminated	A company was terminated

Example webhook event payload

{
    "event": "created",
    "data": {
        "id": "com_sx3svU6K8c5ZkSFlOh5p",
        "legal_name": "Stark Industries, Inc.",
        "trade_name": "Stark Industries",
        "email": "[email protected]",
        "phone": "5551234567",
        "pay_frequency": "biweekly",
        ... // remainder of company object
    }
}

Example terminated company event payload

{
"company": "com_123",
"effectively_terminated_at": "2023-02-02:0000", // datetime
"churn_reason": "switching_providers", // enum of a few possible options
"involuntary_termination_reason": "compliance_risk" // enum of a few possible options
    }
}

More detail on the Company object.

Employee Events

Event	Description
created	An employee was created
updated	An employee was updated
deleted	An employee was deleted

Employees can be terminated by setting the termination_date in the API request, and we will receive an updated webhook with the updated parameters.

Example webhook event payload for an employee

{
    "event": "created",
    "data": {
        "id": "emp_zGGp6wYcxAeu1Ng8IA7v",
        "first_name": "Tony",
        "last_name": "Stark",
        "middle_name": null,
        "email": "[email protected]",
        "dob": "1970-05-29",
        ... // remainder of employee object
    }
}

More detail on the Employee object.

Contractor Events

Event	Description
created	A contractor was created
updated	A contractor was updated
deleted	A contractor was deleted

Contractors can be terminated by setting the termination_date in the API request, and we will receive an updated webhook with the updated parameters.

Example webhook event payload for a contractor

{
    "event": "created",
    "data": {
        "id": "ctr_CyQIKSp6YvU6mBe2a6iq",
        "type": "individual",
        "company": "com_EkIJ9RewumnQLODHv1vl",
        "first_name": "Bruce",
        "middle_name": "Frederick Joseph",
        "last_name": "Springsteen",
        "business_name": null,
        "email": "[email protected]",
        ... // remainder of contractor object
    }
}

More detail on the Contractor object.

Workplace Events

Event	Description
created	A workplace was created
updated	A workplace was updated
deleted	A workplace was deleted

Example webhook event payload for a workplace

{
    "event": "created",
    "data": {
        "id": "wrk_oRgjEaRycoCPuS5TqVkm",
        "name": "New York Office",
        "address": {
            "line1": "200 Park Ave",
            "line2": null,
            "city": "New York",
            "state": "NY",
            "postal_code": "10166",
            "country": "US"
        },
        "company": "com_P7JPeBhb8hH23iiReDQ5"
    }
}

More detail on the Workplace object.

Earning Code Events

Event	Description
created	An earning code was created
updated	An earning code was updated
deleted	An earning code was deleted

Example webhook event payload for an earning code

{
  "event": "created",
  "data": {
    "id": "erc_IR4KiBBB2E6YD2cZjOyn",
    "name": "Sales Commission",
    "type": "commission",
    "company": "com_ccGeW0Etf1UGNPBgQ1Xl"
  }
}

More detail on the Earning Code object.

Payments Webhooks

Event	Description
status_change	A payment status has changed to a non-draft state (processing, paid, failed, refunded)

Example webhook event payload for a payment status update

{
  "event": "status_change",
  "data": {
    "id": "pyt_vIFHhvyGN47ej1upyIT8",
    "status": "paid",
    "amount": "4522.0400",
    "type": "company_cash_requirement",
    "parent_type": "payroll",
    "parent_id": "pay_ENA4k8LMHbgpV07GLGSv",
    "payment_attempts": ...
}

More detail on the Payments object

Federal EIN Verification Events

Event	Description
created	A federal EIN verification was created
updated	A federal EIN verification was updated

Example webhook event payload for a federal EIN verification

{
  "event": "created",
  "data": {
    "id": "fev_D3FeAyR6Ao3LZiO3j6d2",
    "company": "com_097YZQgrXZQb8VHtI76S",
    "legal_name": "Stark Industries, Inc.",
    "federal_ein": "12-3456785",
    "status": "processing",
    "start_time": "2022-07-11T19:37:31.589206Z",
    "end_time": null
  }
}

Requirement Events

Event	Description
created	A requirement was created
updated	A requirement was updated
deleted	A requirement was deleted

Example requirement event payload for a requirement update

{
  "event": "updated",
  "data": {
    "id": "req_D3FeAyR6Ao3LZiO3j6d2",
    "company": "com_097YZQgrXZQb8VHtI76S",
    "requirement": "signatory_identity_verification",
    "categories": ["company_provided_documents"],
    "status": "pending",
    "errors": [],
    "guidance": {
        "document_options": [{
            "name": "signatory_photo_id", 
            "label": "Non-expired government-issued photo ID for authorized signer",
        }],   
    },
  }
}

Company Processing Status Events

Event	Description
status_change	A company's processing period or ability changes. For example, a company on four-day processing is upgraded to two-day processing after demonstrating continuous creditworthiness, or a company is exited.

Example webhook event for a company graduated to two-day processing

{
  "event": "status_change",
  "data": {
    "id": "com_sx3svU6K8c5ZkSFlOh5p",
    "legal_name": "Stark Industries, Inc.",
    "implementation": {
      "status": "completed",
      "remaining_steps": {
        "kyb": {
          "status": "two_day_approved"
        }
      }
    },
    "processing_period": "two_day",
    ... // remainder of company object
  }
}

Example webhook event for a company downgraded from two-day to four-day processing

{
  "event": "status_change",
  "data": {
    "id": "com_sx3svU6K8c5ZkSFlOh5p",
    "legal_name": "Stark Industries, Inc.",
    "implementation": {
      "status": "completed",
      "remaining_steps": {
        "kyb": {
          "status": "four_day_approved"
        }
      }
    },
    "processing_period": "four_day",
    ... // remainder of company object
  }
}

Example webhook event for a company that has been terminated after repeated funding failures

{
  "event": "status_change",
  "data": {
    "id": "com_sx3svU6K8c5ZkSFlOh5p",
    "legal_name": "Stark Industries, Inc.",
    "implementation": {
      "status": "completed",
      "remaining_steps": {
        "kyb": {
          "status": "denied"
        }
      }
    },
    "processing_period": "four_day",
    ... // remainder of company object
  }
}

Pay Schedule Events

Event	Description
created	A pay schedule was created
updated	A pay schedule was updated
deleted	A pay schedule was deleted

Example webhook event payload for a pay schedule creation

{
  "event": "created",
  "data": {
    "id": "psc_KpOEeeH3kWMrxyzffjcn",
    "company": "com_FeToKDOuUyvQrQADcY2u",
    "name": "Test Schedule",
    "pay_frequency": "biweekly",
    "first_payday": "2021-04-16",
    "second_payday": null,
    "first_period_end": "2021-04-12",
    "metadata": {}
  }
}

Earning Rate Events

Event	Description
created	An earning rate was created
updated	An earning rate was updated

Example webhook event payload for an earning rate creation

{
  "event": "created",
  "data": {
    "id": "rte_aOSqW0QTKcE1iVU1C5",
    "amount": "11.25",
    "period": "hourly",
    "employee": "emp_aslkj192j3laksdj",
    "name": "Dishwasher Weekend Rate",
    "active": true,
    "metadata": {}
  }
}

Tax Filing Event

Event	Description
created	A tax filing was created
updated	A tax filing was updated
status_change	The status of a tax filing has changed
deleted	A tax filing has been deleted

Example webhook event payload for a tax filing

{
  "event": "created",
  "data": {
    "id": "flg_GaeJoEAzbqqc2D9GMfOF",
    "company": "com_vIFHhvyGN47ej1upyIT8",
    "year": 2023,
    "description": "Michigan State Unemployment Tax",  
    "frequency": "quarterly",
    "period": "q2",
    "status": "filed",
    "can_retry": false,
    "tax_filing_events": [
      {
        "id": "fev_jIFHhvyGN47ej1upyIT8",
        "tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
        "status": "filed",
        "created_at": "2023-04-12T21:32:44.957364Z",
        "category": null,
        "label": null,
        "account_number": "123456789",
      },
      {
        "id": "fev_jupyIT8upyIT8upyIT87",
        "tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
        "status": "submitted",
        "created_at": "2023-04-12T21:32:44.957364Z",
        "category": null,
        "label": null,
        "account_number": "123456789",
      },
      {
        "id": "fev_jHhvyHhvyHhvyHhvyHhv",
        "tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
        "status": "pending",
        "created_at": "2023-04-12T21:32:44.957364Z",
        "category": null,
        "label": null,
        "account_number": "123456789",
      },
      {
        "id": "fev_7ej1upy7ej1upy7ej1up",
        "tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
        "status": "rejected",
        "created_at": "2023-04-12T21:32:44.957364Z",
        "category": "applied_for_invalid_ein",
        "label": "EIN is either invalid or Applied For. Return will not be accepted by the agency. If filed, the agency will reject the return",
        "account_number": "Applied For",
      },
      {
        "id": "fev_pyITpyITpyITpyITpyIT",
        "tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
        "status": "submitted",
        "created_at": "2023-04-12T21:32:44.957364Z",
        "category": null,
        "label": null,
        "account_number": "Applied For",
      },
      {
        "id": "fev_GN47eGN47eGN47eGN47e",
        "tax_filing": "flg_jIFHhvyGN47ej1upyIT8",
        "status": "pending",
        "created_at": "2023-04-12T21:32:44.957364Z",
        "category": null,
        "label": null,
        "account_number": "Applied For",
      },
    ],
  }
}

Net Pay Split Events

Event	Description
created	A net pay split was created
updated	A net pay split was updated

Example webhook event payload for a net pay split creation

{
  "event": "created",
  "data": {
    "id": "nps_1b951IjHG4w3yFQtpIwg", 
    "splits": [
      {
        "amount": "50.00", 
        "priority": 1, 
        "percentage": null, 
        "bank_account": "bnk_pli2zS8ulTsz82gSrvh3"
      }, 
      {
        "amount": "0.00", 
        "priority": 2, 
        "percentage": null, 
        "bank_account": "bnk_sTy2YqAYFi7hO2Eu4wNg"
      }
    ], 
    "employee": "emp_qZRfe3o34Rw5s3bPgUnr", 
    "contractor": null, 
    "is_default": true, 
    "deactivated_at": null, 
    "deactivated_reason": null
  }
}

Integration Access Events

Event	Description
created	An integration access was created
updated	An integration access was updated
deleted	An integration access was deleted

Example webhook event payload for an integration access creation

{
  "event": "created",
  "data": {
    "id": "iac_fVSfFvta4PucEMEe4Tsg", 
    "scope": ["company:retrieve", 
              "company_tax_document:list", 
              "document:download", 
              "employee:list", 
              "employee:retrieve", 
              "payroll:list", 
              "payroll:retrieve", 
              "payroll_item:retrieve", 
              "benefits:list", 
              "benefits:retrieve", 
              "benefits:partial_update", 
              "benefits:create", 
              "benefits:destroy", 
              "integration_access:retrieve", 
              "integration_partners:list", 
              "integration_partners:retrieve", 
              "integration_partners:authorize"], 
    "status": "pending", 
    "company": "com_yQqZgGvyG5oFwsihlipd", 
    "metadata": {}, 
    "access_type": "integrated", 
    "integration_partner": "int_Xf90bJAKE9Lf2jVjbgne", 
    "integration_permission": "ipe_nzP0UQPBTefnsHe16Are"
  }
}

Enrollment Profile Events

Event	Description
created	An Enrollment Profile was created
updated	An Enrollment Profile was updated

{
  "event": "created",
  "data": {
    "company": "com_vIFHhvyGN47ej1upyIT8",
    "user_since": null,
    "fraud_score": null,
    "paying_user": null,
    "social_media": [],
    "employee_count": 120,
    "enrollment_mode": "implementation_services",
    "predicted_fraud": null,
    "account_contacts": [],
    "contractor_count": null,
    "pay_period_amount": null,
    "expected_first_payday": null,
    "first_payroll_of_year": null,
    "missed_payments_count": null,
    "earliest_known_revenue": null,
    "products_actively_used": [],
    "average_monthly_revenue": null,
    "previous_payroll_provider": null,
    "payroll_history_access_method": null,
    "approved_for_payment_processing": null,
    "months_on_previous_payroll_provider": null,
    "previous_payroll_provider_account_id": null,
    "implementation_services_submission_comment": null,
    "existing_payroll_customer_processing_period": null
  }
}