Company Connect Webhook Events

Company Connect webhook events will notify you when the data for a given company connection is ready to be retrieved. The payload is summary information, not the data itself. After receiving a webhook event, call the corresponding endpoint to retrieve the account data.

company_connect.census.added

Employee census data for your company connection is available. Use company_connection_id in the payload to query the List Employees endpoint to fetch the data.

Payload Schema

Payload Param	Type	Description
`company_connection_id`	string	UUID of the Company Connection.
`company_name`	string	Company name, created by you, used to name the Company Connection.
`outcome`	string	The outcome of the job, either `success`, `error`, or `pending`. If `pending` you will receive another webhook with `outcome` as `success` or `error` within 24 hours.
`error_code` (optional)	string	On error, a string describing the error.
`error_type` (optional)	string	On error, a high level classification of the error.
`added`	array	An array of employee IDs for whom new records were added.
`updated`	array	An array of employee IDs for whom records were updated.
`deleted`	array	An array of employee IDs for whom records were deleted.

Sample Webhook Event

{
  "event": "company_connect.census.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "company_connection_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "company_name": "Acme",
    "outcome": "success",
    "added": ['001234', '001235', '001236'],
    "updated": [],
    "deleted": [],
  }
}

company_connect.employments.added

Employments data for your company connection is available. Use company_connection_id in the payload to query the List Employments Data endpoint to fetch the data.

Payload Schema

Payload Param	Type	Description
`company_connection_id`	string	UUID of the Company Connection.
`company_name`	string	Company name, created by you, used to name the Company Connection.
`outcome`	string	The outcome of the job, either `success`, `error`, or `pending`. If `pending` you will receive another webhook with `outcome` as `success` or `error` within 24 hours.
`error_code` (optional)	string	On error, a string describing the error.
`error_type` (optional)	string	On error, a high level classification of the error.
`added`	array	An array of employee IDs for whom new records were added.
`updated`	array	An array of employee IDs for whom records were updated.
`deleted`	array	An array of employee IDs for whom records were deleted.

Sample Webhook Event

{
  "event": "company_connect.employments.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "company_connection_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "company_name": "Acme",
    "outcome": "success",
    "added": ['001234', '001235', '001236'],
    "updated": [],
    "deleted": [],
  }
}

company_connect.incomes.added

Employee census data for your company connection is available. Use company_connection_id in the payload to query the List Employee Incomes endpoint to fetch the data.

Payload Schema

Payload Param	Type	Description
`company_connection_id`	string	UUID of the Company Connection.
`company_name`	string	Company name, created by you, used to name the Company Connection.
`outcome`	string	The outcome of the job, either `success`, `error`, or `pending`. If `pending` you will receive another webhook with `outcome` as `success` or `error` within 24 hours.
`error_code` (optional)	string	On error, a string describing the error.
`error_type` (optional)	string	On error, a high level classification of the error.
`added`	array	An array of employee IDs for whom new records were added.
`updated`	array	An array of employee IDs for whom records were updated.
`deleted`	array	An array of employee IDs for whom records were deleted.

Sample Webhook Event

{
  "event": "company_connect.incomes.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "company_connection_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "company_name": "Acme",
    "outcome": "success",
    "added": ['001234', '001235', '001236'],
    "updated": [],
    "deleted": [],
  }
}

company_connect.status.updated

The status of the Company Connection has changed. See Company Connection status for more on status and how they transition.

Payload Schema

Payload Param	Type	Description
`company_connection_id`	string	UUID of the Company Connection.
`company_name`	string	Company name, created by you, used to name the Company Connection.
`status`	string	The current status of the Company Connection.
`previous_status`	string	The previous status of the Company Connection.
`status_updated_at`	string	ISO 8601 timestamp of when the Company Connection's `status` transitioned from `previous_status`

Sample Webhook Event

{
  "event": "company_connect.status.updated",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "company_connection_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "company_name": "Acme",
    "status": "data_available",
    "previous_status": "processing",
    "status_updated_at": "2023-09-28T02:03:47+00:00"
  }
}