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.
`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"
  }
}

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.
`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"
  }
}

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.
`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"
  }
}

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

Sample Webhook Event

{
  "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",
    "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
    }
  }
}

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.
`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",
    "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",
    "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",
    "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",
    "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.
`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",
    "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.
`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",
    "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",
    "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",
    "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",
    "params": {
      "count": 20
    }
  }
}

verification_reports.refreshed

Verification reports for a user have been refreshed. Use end_user_id in the payload to query either GET /v1/end_users/{id}/verification_reports/voe or GET /v1/end_users/{id}/verification_reports/voie to fetch the most up-to-date verification report data.

Payload Schema

Payload Param	Type	Description
`end_user_id`	string	The user identifier you specified when the user initially connected to the payroll account, if provided.
`availability`	object	See child attributes for details.
`availability.voe`	object	Availability of the Verification of Employment report. See Availability Schema below for object structure.
`availability.voie`	object	Availability of the Verification of Income and Employment report. See Availability Schema below for object structure.

Availability Schema

Parameter	Type	Description
`status`	string	Either `available`, if the verification report is able to be retrieved, or `unavailable`, if the report is not available due to missing required data.
`updated_at`	string	ISO 8601 timestamp of when the verification report most recently had a data change (e.g., the user received a new paystub which increases their gross pay for the year).
`refreshed_at`	string	ISO 8601 timestamp of when the data underlying the verification report was most recently checked for changes.

Sample Webhook Event

{
  "event": "verification_reports.refreshed",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "end_user_id": "my_user_12345",
    "availability": {
      "voe": {"status": "available", "updated_at": "2021-01-12T02:36:01.287148+00:00", "refreshed_at": "2021-01-12T02:36:01.287148+00:00"},
      "voie": {"status": "available", "updated_at": "2021-01-12T02:36:01.287148+00:00", "refreshed_at": "2021-01-12T02:36:01.287148+00:00"}
    }
  }
}