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.
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 |
Payroll Events
Event | Description |
---|---|
status_change | A payroll instance's status changes (for example, a payroll moves from pending to processing ). |
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) |
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 |
deleted | A company was deleted |
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
}
}
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 |
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 |
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_verification",
"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
}
}
Updated 4 months ago