Income and Employment Webhook Events

Income and Employment webhook events will notify you when the data for a given product 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.

employment.added

Employment data for the payroll account is available. Use account_id in the payload to query the Get Employment endpoint to fetch the data.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`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.
`params` (optional)	object	Parameters of the job, if applicable.
`timestamp`	string	ISO 8601 timestamp of job completion.
`name`	string	Name of the job, which is `employment`.
`link_token_id`	string	UUID of Link token used to initialize Link, or an undefined link token if triggered by a refresh job (such as from Monitoring). You should use `account_id` as the main identifier.
`id`	string	Deprecated. UUID of the job. You should use `account_id` as the main identifier.

Sample Webhook Event

{
  "event": "employment.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "employment",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null
  }
}

identity.added

Identity data for the payroll account is available. Use account_id in the payload to query the Get Identity endpoint to fetch the data.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`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.
`params` (optional)	object	Parameters of the job, if applicable.
`timestamp`	string	ISO 8601 timestamp of job completion.
`name`	string	Name of the job, which is `identity`.
`link_token_id`	string	UUID of Link token used to initialize Link, or an undefined link token if triggered by a refresh job (such as from Monitoring). You should use `account_id` as the main identifier.
`id`	string	Deprecated. UUID of the job. You should use `account_id` as the main identifier.

Sample Webhook Event

{
  "event": "identity.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "identity",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null
  }
}

income.added

Income data for the payroll account is available. Use account_id in the payload to query the Get Income endpoint to fetch the data.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`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.
`params` (optional)	object	Parameters of the job, if applicable.
`timestamp`	string	ISO 8601 timestamp of job completion.
`name`	string	Name of the job, which is `income`.
`link_token_id`	string	UUID of Link token used to initialize Link, or an undefined link token if triggered by a refresh job (such as from Monitoring). You should use `account_id` as the main identifier.
`id`	string	Deprecated. UUID of the job. You should use `account_id` as the main identifier.

Sample Webhook Event

{
  "event": "income.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "income",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null
  }
}

paystubs.added

A set of Paystubs are available. The params describes which paystubs. Use account_id in the payload to query the Get Paystub endpoint to fetch them.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`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.
`params`	object	Parameters of the job, if applicable.
`error_code` (optional)	string	On error, a string describing the error.
`error_type` (optional)	string	On error, a high level classification of the error.
`timestamp`	string	ISO 8601 timestamp of job completion.
`name`	string	Name of the job, which is `paystubs`.
`added`	array	A list of objects specifying IDs of the new paystubs that were added to the payroll account.
`deleted`	array	A list of objects specifying IDs of the old paystubs that were removed from the payroll account.
`link_token_id`	string	UUID of Link token used to initialize Link, or an undefined link token if triggered by a refresh job (such as from Monitoring). You should use `account_id` as the main identifier.
`id`	string	Deprecated. UUID of the job. You should use `account_id` as the main identifier.

Note: For paystubs_documents, you will receive a paystubs.documents.added webhook which will include an added payload parameter that specifies the IDs of paystubs which have a new document.

Sample Webhook Events

{
  "event": "paystubs.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "paystubs",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "added": [{"id": "dbff9830-55ce-4aa5-82f1-e04f196da041"}],
    "deleted": [{"id": "57043868-6fb3-47e8-a2b7-c993bd023f25"}],
    "params": {
      "from_pay_date": "2020-10-01",
      "to_pay_date": "2020-12-31",
      "count": 6,
      "sync_status": "in_progress",
      "has_potential_paystubs_documents": True
    }
  }
}

{
  "event": "paystubs.documents.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "paystubs_documents",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "added": [{"id": "dbff9830-55ce-4aa5-82f1-e04f196da041"}],
    "params": {
      "from_pay_date": "2020-10-01",
      "to_pay_date": "2020-12-31",
      "count": 6,
      "sync_status": "in_progress",
    }
  }
}

Paystubs Sync Events

A paystubs sync event will trigger as soon as the relevant data has been retrieved. If there isn't enough data to meet the 30d or 90d threshold, that event will be skipped. The sync status events are:

paystubs.seven_days_synced: Triggered when 7 days of paystubs have been collected
paystubs.thirty_days_synced: Triggered when 30 days of paystubs have been collected
paystubs.ninety_days_synced: Triggered when 90 days of paystubs have been collected
paystubs.fully_synced: Triggered when all available paystubs have been collected

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`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.
`params`	object	Parameters of the job, if applicable.
`error_code` (optional)	string	On error, a string describing the error.
`error_type` (optional)	string	On error, a high level classification of the error.
`timestamp`	string	ISO 8601 timestamp of job completion.
`name`	string	Name of the job, which is `paystubs`.
`link_token_id`	string	UUID of Link token used to initialize Link, or an undefined link token if triggered by a refresh job (such as from Monitoring). You should use `account_id` as the main identifier.
`id`	string	Deprecated. UUID of the job. You should use `account_id` as the main identifier.

Sample Webhook Events

{
  "event": "paystubs.seven_days_synced",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "paystubs",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "params": {
      "from_pay_date": "2020-12-15",
      "to_pay_date": "2020-12-21",
      "count": 1,
      "has_potential_paystubs_documents": True
    }
  }
}

{
  "event": "paystubs.thirty_days_synced",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "paystubs",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "params": {
      "from_pay_date": "2020-11-20",
      "to_pay_date": "2020-12-14",
      "count": 2,
      "has_potential_paystubs_documents": True
    }
  }
}

{
  "event": "paystubs.ninety_days_synced",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "paystubs",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "params": {
      "from_pay_date": "2020-08-15",
      "to_pay_date": "2020-11-29",
      "count": 6,
      "has_potential_paystubs_documents": True
    }
  }
}

{
  "event": "paystubs.fully_synced",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "paystubs",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "params": {
      "from_pay_date": "2020-08-01",
      "to_pay_date": "2020-08-14",
      "count": 2,
      "has_potential_paystubs_documents": False
    }
  }
}

shifts.added

A set of Shifts are available. The params describes the number of shifts. Use account_id in the payload to query the List Shifts endpoint to fetch them.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`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.
`params` (optional)	object	Input parameters to the job, if applicable.
`error_code` (optional)	string	On error, a string describing the error.
`timestamp`	string	ISO 8601 timestamp of job completion.
`name`	string	Name of the job, which is `shifts`.
`added`	array	A list of objects specifying IDs of the new shifts that were added to the payroll account.
`deleted`	array	A list of objects specifying IDs of the old shifts that were removed from the payroll account.
`link_token_id`	string	UUID of Link token used to initialize Link, or an undefined link token if triggered by a refresh job (such as from Monitoring). You should use `account_id` as the main identifier.
`id`	string	Deprecated. UUID of the job. You should use `account_id` as the main identifier.

Sample Webhook Event

{
  "event": "shifts.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "shifts",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "added": [{"id": "dbff9830-55ce-4aa5-82f1-e04f196da041"}],
    "deleted": [{"id": "57043868-6fb3-47e8-a2b7-c993bd023f25"}],
    "params": {
      "count": 14,
      "sync_status": "complete",
    }
  }
}

Shifts Sync Events

A shifts sync event will trigger as soon as the relevant data has been retrieved. If there isn't enough data to meet the 30d or 90d threshold, that event will be skipped. The sync status events are:

shifts.seven_days_synced: Triggered when 7 days of shifts have been collected
shifts.thirty_days_synced: Triggered when 30 days of shifts have been collected
shifts.ninety_days_synced: Triggered when 90 days of shifts have been collected
shifts.fully_synced: Triggered when all available shifts have been collected

Note that only 90 days of data are collected for shifts. Thus, shifts.ninety_days_synced and shifts.fully_synced will trigger at the same time.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`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.
`params`	object	Parameters of the job, if applicable.
`error_code` (optional)	string	On error, a string describing the error.
`error_type` (optional)	string	On error, a high level classification of the error.
`timestamp`	string	ISO 8601 timestamp of job completion.
`name`	string	Name of the job, which is `shifts`.
`link_token_id`	string	UUID of Link token used to initialize Link, or an undefined link token if triggered by a refresh job (such as from Monitoring). You should use `account_id` as the main identifier.
`id`	string	Deprecated. UUID of the job. You should use `account_id` as the main identifier.

Sample Webhook Event

{
  "event": "shifts.seven_days_synced",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "shifts",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "params": {
      "count": 6
    }
  }
}

{
  "event": "shifts.thirty_days_synced",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "shifts",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "params": {
      "count": 20
    }
  }
}

{
  "event": "shifts.ninety_days_synced",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "shifts",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "params": {
      "count": 20
    }
  }
}

{
  "event": "shifts.fully_synced",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "shifts",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "error_code": null,
    "error_type": null,
    "params": {
      "count": 20
    }
  }
}