Webhook Event Types

A list of Check supported webhook events

Check-Topic header

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

TopicDescription
payrollAny payroll lifecycle event
company_tax_documentAny company tax document event
company_authorization_documentAny company authorization document event
employee_tax_documentAny employee tax document event
contractor_tax_documentAny contractor tax document event
setup_documentAny setup document event
bank_accountAny bank account event
benefitAny benefit event
company_benefitAny company benefit event
post_tax_deductionAny post-tax deduction event
companyAny company event
employeeAny employee event
contractorAny contractor event
workplaceAny workplace event
earning_codeAny earning code event
paymentAny payment status change event
federal_ein_verificationAny federal EIN verification change event
requirementAny Requirements API events
company_processing_statusAny company processing status change event
pay_scheduleAny pay schedule event
earning_rateAny earning rate event
tax_filingAny tax filing event
net_pay_splitAny net pay split event
integration_accessAny integration access event
enrollment_profileAny enrollment profile event

Payroll Events

EventDescription
status_changeA payroll instance's status changes (for example, a payroll moves from pending to processing).
createdA payroll was created
deletedA 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.

EventDescription
createdA document was created (For example, this could be triggered when an employee submits a document through Check Onboard)
deletedA 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

EventDescription
createdA bank account was created
updatedA bank account was updated
deletedA 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

EventDescription
createdA benefit was created
updatedA benefit was updated
deletedA 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

EventDescription
createdA company benefit was created
updatedA company benefit was updated
deletedA 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

EventDescription
createdA post tax deduction was created
updatedA post tax deduction was updated
deletedA 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

EventDescription
createdA company was created
updatedA company was updated
terminatedA 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

EventDescription
createdAn employee was created
updatedAn employee was updated
deletedAn 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

EventDescription
createdA contractor was created
updatedA contractor was updated
deletedA 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

EventDescription
createdA workplace was created
updatedA workplace was updated
deletedA 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

EventDescription
createdAn earning code was created
updatedAn earning code was updated
deletedAn 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

EventDescription
status_changeA 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

EventDescription
createdA federal EIN verification was created
updatedA 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

EventDescription
createdA requirement was created
updatedA requirement was updated
deletedA 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

EventDescription
status_changeA 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.

🚧

Note on applicability of Company Processing Status events

The Company Processing Status webhooks only apply to cases where a company is automatically graduated to accelerated processing or downgraded to 4-day processing by Check’s Graduation and Downgrade & Exit policy.

To capture all processing period changes, please refer to the Company webhook event type.

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

EventDescription
createdA pay schedule was created
updatedA pay schedule was updated
deletedA 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

EventDescription
createdAn earning rate was created
updatedAn 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

EventDescription
createdA tax filing was created
updatedA tax filing was updated
status_changeThe status of a tax filing has changed
deletedA 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

EventDescription
createdA net pay split was created
updatedA 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

EventDescription
createdAn integration access was created
updatedAn integration access was updated
deletedAn 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

EventDescription
createdAn Enrollment Profile was created
updatedAn 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,
    "first_payroll": 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
  }
}