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.
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. |
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
| 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,
"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
}
}
Updated about 2 months ago