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

Payroll Events

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

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

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
deletedA 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

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

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

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_verification",
    "errors": [],
    "guidance": {
        "document_options": [{
            "name": "signatory_photo_id", 
            "label": "Non-expired government-issued photo ID for authorized signer",
        }],   
    },
  }
}