GuidesAPI ReferenceChangelog
Log In

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 ParamTypeDescription
account_idstringUUID of the payroll account.
end_user_idstringThe user identifier you specified when the user initially connected to the payroll account, if provided.
outcomestringThe 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)stringOn error, a string describing the error.
error_type (optional)stringOn error, a high level classification of the error.
params (optional)objectParameters of the job, if applicable.
timestampstringISO 8601 timestamp of job completion.
namestringName of the job, which is employment.
link_token_idstringUUID 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.
idstringDeprecated. 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 ParamTypeDescription
account_idstringUUID of the payroll account.
end_user_idstringThe user identifier you specified when the user initially connected to the payroll account, if provided.
outcomestringThe 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)stringOn error, a string describing the error.
error_type (optional)stringOn error, a high level classification of the error.
params (optional)objectParameters of the job, if applicable.
timestampstringISO 8601 timestamp of job completion.
namestringName of the job, which is identity.
link_token_idstringUUID 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.
idstringDeprecated. 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 ParamTypeDescription
account_idstringUUID of the payroll account.
end_user_idstringThe user identifier you specified when the user initially connected to the payroll account, if provided.
outcomestringThe 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)stringOn error, a string describing the error.
error_type (optional)stringOn error, a high level classification of the error.
params (optional)objectParameters of the job, if applicable.
timestampstringISO 8601 timestamp of job completion.
namestringName of the job, which is income.
link_token_idstringUUID 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.
idstringDeprecated. 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 ParamTypeDescription
account_idstringUUID of the payroll account.
end_user_idstringThe user identifier you specified when the user initially connected to the payroll account, if provided.
outcomestringThe 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.
paramsobjectParameters of the job, if applicable.
error_code (optional)stringOn error, a string describing the error.
error_type (optional)stringOn error, a high level classification of the error.
timestampstringISO 8601 timestamp of job completion.
namestringName of the job, which is paystubs.
addedarrayA list of objects specifying IDs of the new paystubs that were added to the payroll account.
deletedarrayA list of objects specifying IDs of the old paystubs that were removed from the payroll account.
link_token_idstringUUID 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.
idstringDeprecated. 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 ParamTypeDescription
account_idstringUUID of the payroll account.
end_user_idstringThe user identifier you specified when the user initially connected to the payroll account, if provided.
outcomestringThe 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.
paramsobjectParameters of the job, if applicable.
error_code (optional)stringOn error, a string describing the error.
error_type (optional)stringOn error, a high level classification of the error.
timestampstringISO 8601 timestamp of job completion.
namestringName of the job, which is paystubs.
link_token_idstringUUID 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.
idstringDeprecated. 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 ParamTypeDescription
account_idstringUUID of the payroll account.
end_user_idstringThe user identifier you specified when the user initially connected to the payroll account, if provided.
outcomestringThe 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)objectInput parameters to the job, if applicable.
error_code (optional)stringOn error, a string describing the error.
timestampstringISO 8601 timestamp of job completion.
namestringName of the job, which is shifts.
addedarrayA list of objects specifying IDs of the new shifts that were added to the payroll account.
deletedarrayA list of objects specifying IDs of the old shifts that were removed from the payroll account.
link_token_idstringUUID 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.
idstringDeprecated. 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 ParamTypeDescription
account_idstringUUID of the payroll account.
end_user_idstringThe user identifier you specified when the user initially connected to the payroll account, if provided.
outcomestringThe 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.
paramsobjectParameters of the job, if applicable.
error_code (optional)stringOn error, a string describing the error.
error_type (optional)stringOn error, a high level classification of the error.
timestampstringISO 8601 timestamp of job completion.
namestringName of the job, which is shifts.
link_token_idstringUUID 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.
idstringDeprecated. 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
    }
  }
}