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 |
|---|---|
| created | A payroll was created |
| deleted | A payroll was deleted |
| updated | A payroll was updated Note: This event is available in API version 2025-01-01 or later. |
| status_change | A payroll instance's status changes (for example, a payroll moves from pending to processing). Note: This event was deprecated in API version 2025-01-01. |
Example webhook event payload
{
"event": "created",
"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 |
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
}
}Company Terminated Events
| Event | Description |
|---|---|
| created | A company termination was created |
Check sends this event once, when a company's termination is recorded. Check does not send another termination event when a termination is later changed.
Terminated company payload fields
| Attribute | Description |
|---|---|
company | Public ID of the terminated company. |
effectively_terminated_at | When the company was effectively terminated. |
churn_reason | Voluntary termination reason. null when the termination was involuntary. |
involuntary_termination_reason | Involuntary termination reason. null when the termination was voluntary. |
Exactly one of churn_reason or involuntary_termination_reason is non-null.
Partner-selectable involuntary values are customer_not_paying_partner and chargeback. The voluntary churn_reason value price indicates the employer left due to pricing.
Webhook payloads may include other involuntary_termination_reason values when Check initiates the termination (for example compliance_risk or funding_failure_strikes). Treat both reason fields as open enums and tolerate unknown values.
Example voluntary termination event payload
{
"event": "created",
"data": {
"company": "com_123",
"effectively_terminated_at": "2023-02-02T00:00:00Z",
"churn_reason": "price",
"involuntary_termination_reason": null
}
}Example involuntary termination event payload
{
"event": "created",
"data": {
"company": "com_123",
"effectively_terminated_at": "2023-02-02T00:00:00Z",
"churn_reason": null,
"involuntary_termination_reason": "chargeback"
}
}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 three-day processing is upgraded to two-day processing after demonstrating continuous creditworthiness, or a company is exited. |
Note on applicability of Company Processing Status eventsThe Company Processing Status webhooks only apply to cases where a company is automatically graduated to accelerated processing or downgraded to 3-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 three-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": "three_day",
... // remainder of company object
}
}Example webhook event for a company whose KYB status is set to denied 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": "three_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": {}
}
}[Deprecating Soon] 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",
},
],
}
}Company Filing Event
| Event | Description |
|---|---|
| created | A filing was created |
| updated | A filing was updated |
| deleted | A filing was deleted |
Example webhook event payload for a company filing
{
"event": "updated",
"data": {
"id": "com_fil_9kL2mN8pQ4rS6tU1vW3x",
"company": "com_7bF9dG2hJ5kM8nP1qR4s",
"year": 2024,
"period": "q1",
"label": "Federal Quarterly Filing - Q1",
"due_at": "2024-04-15",
"filed_at": "2024-04-12T16:30:25.847Z",
"document": "doc_3aE6fH9iL2mO5pR8sV1y",
"filing_attempts": 2,
"status": "filed",
"status_history": [
{
"status": "inapplicable",
"status_at": "2024-01-15T10:30:15.423Z",
"blocked_reasons": []
},
{
"status": "pending",
"status_at": "2024-01-20T14:45:32.156Z",
"blocked_reasons": []
},
{
"status": "blocked",
"status_at": "2024-03-10T09:15:48.792Z",
"blocked_reasons": [
{
"type": "applied_for_tax_id",
"resource_type": "company_tax_param",
"resource": "spa_h7zSw4NITCtef4Taf5yA"
}
]
},
{
"status": "pending",
"status_at": "2024-03-12T11:20:07.234Z",
"blocked_reasons": []
},
{
"status": "filed",
"status_at": "2024-04-12T16:30:25.847Z",
"blocked_reasons": []
}
]
}
}Tax Package Events
| Event | Description |
|---|---|
| status_change | A tax package finished or failed generating |
Check sends this event once per tax package, when generation finishes and the package's status becomes succeeded or failed. Check does not send an event when generation starts. A failed package arrives with status: failed, result set to null, and error set.
In the webhook payload, result.url is a relative path, such as /tax_packages/tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3/download. To get the package, call Download a tax package (GET /tax_packages/:id/download) with the package id instead of hard-coding a host onto that path.
Example webhook event payload for a tax package that finished generating
{
"event": "status_change",
"data": {
"id": "tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3",
"company": "com_myKIvCGb7M86G2CQbYe5",
"status": "succeeded",
"contents": {
"employee_tax_statements": ["ets_123", "ets_456"],
"filings": ["com_fil_999"]
},
"created_at": "2024-11-03T19:52:15Z",
"succeeded_at": "2024-11-03T19:55:11Z",
"result": {
"url": "/tax_packages/tax_pkg_1MrQwrLkdIwHu7ixUov4x2b3/download"
},
"error": null
}
}More detail on the Tax Package object.
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
}
}
Setup Events
| Event | Description |
|---|---|
| created | A Setup was created |
| updated | A Setup was updated |
{
"event": "updated",
"data": {
"id": "ese_aBs7J2B2lk91ba8jjaa2",
"phases": [
{
"name": "preliminary_review",
"completed_at": "2025-02-21T13:30:45.431544Z"
},
{
"name": "team_setup",
"completed_at": "2025-03-06T21:39:55.661535Z"
},
{
"name": "final_steps",
"completed_at": "2025-03-06T22:00:33.323800Z"
}
],
"company": "com_Omi4cyBa7sj1baLwj1b2",
"profile": {
"first_payroll": false,
"employee_count": 31,
"contractor_count": 0,
"first_payroll_of_year": null,
"previous_payroll_provider": "Toast"
},
"closed_at": null,
"setup_due": "2025-03-10T00:00:00Z",
"created_at": "2025-02-12T14:40:57.221345Z",
"completed_at": null,
"submitted_at": "2025-02-12T14:40:57.250418Z"
}
}Fulfillment Events
| Event | Description |
|---|---|
| created | A fulfillment was created |
| deleted | A fulfillment was deleted |
Example webhook event payload for a fulfillment
{
"event": "created",
"data": {
"id": "ful_abc123def456",
"company": "com_sx3svU6K8c5ZkSFlOh5p",
"payment": "pyt_xyz789ghi012"
}
}More detail on the Fulfillment object.
Correction Events
The Correction API is currently in limited preview, and is not yet generally available.
| Event | Description |
|---|---|
| created | A correction was created |
| updated | A correction was updated |
| deleted | A correction was deleted |
An updated event is sent when a correction's preview or approval starts or completes, when the correction is updated or reopened, when a payroll is added to or deleted from it, and when its status moves to processing, settled, or failed. See Corrections for details.
Example webhook event payload for a correction
{
"event": "updated",
"data": {
"id": "cor_Bw6EkMDmxCPeVQ2eYzLu",
"description": "Void and replace 3/31 payroll for J. Smith",
"company": "com_sx3svU6K8c5ZkSFlOh5p",
"year": 2026,
"status": "draft",
"preview": {
"status": "succeeded",
"started_at": "2026-06-29T18:26:56.848920Z",
"messages": null
},
"approval": null,
"settlement_date": "2026-07-15",
...
}
}More detail on the Correction object.
Employee Tax Statement Override Events
| Event | Description |
|---|---|
| created | An employee tax statement override was created |
| updated | An employee tax statement override was updated |
| deleted | An employee tax statement override was deleted |
An updated event is sent for every existing override saved by Create or update employee tax statement overrides, even if no values changed, and by Update an employee tax statement override only when a value changes.
Example webhook event payload for an employee tax statement override
{
"event": "updated",
"data": {
"id": "ets_ovr_Hq3nVb7KcWz2LpRtYe9m",
"company": "com_sx3svU6K8c5ZkSFlOh5p",
"employee": "emp_OBfYZbVSadBmQZcU7wN2",
"year": 2026,
"qualified_overtime_compensation": "950.00",
"other_lines": [
{
"label": "PUCC",
"amount": "4200.00"
}
],
"metadata": {},
"created_at": "2027-01-08T15:02:11.482915Z",
"updated_at": "2027-01-12T10:41:37.105233Z"
}
}More detail on the Employee tax statement override object.
Notification Events
| Event | Description |
|---|---|
| created | A Notification was created |
Example webhook event payload for a notification creation
{
"event": "created",
"data": {
"id": "ntf_MrFrw0F82NSJjyw10Erk",
"topic": "ready_for_payroll",
"company": "com_zH8Gq33iBkFj5o0GKjTw",
"recipient_type": "company",
"recipient": "com_zH8Gq33iBkFj5o0GKjTw",
"email_communication": "cmn_MrFrw0F82NSJjyw10Erk",
"created_at": "2024-01-15T10:30:00Z"
}
}Updated about 13 hours ago