Subscribe to these events via Webhooks to track Task progress and data availability in real time.
All webhook payloads include the common fields (webhook_id, event_type, event_created_at, updated_at, user_id, template_id) plus the event-specific fields below.
task-status-updated
Fires for each Task status change during the connection lifecycle. This is the primary event for tracking verification progress.
Additional fields:
| Field | Description |
|---|
task_id | The Task identifier |
link_id | Account connection ID (use to retrieve access_token) |
product | income, employment, or admin |
data_source | payroll, docs, insurance, financial_accounts, or tax |
tracking_info | Custom metadata passed via bridge_token (nullable) |
status | Current task status (see Connection Lifecycle) |
{
"webhook_id": "488f424096d3461aa0e4cf11a985f6df",
"task_id": "521442a087604e599c637db310d07402",
"link_id": "d39d86dcc20c46e0ae75ba9ab1311a21",
"product": "income",
"data_source": "payroll",
"tracking_info": null,
"event_type": "task-status-updated",
"event_created_at": "2022-08-24T13:55:12.845645Z",
"updated_at": "2022-08-24T13:55:12.845666+00:00",
"status": "done",
"user_id": "88fef4cea64c40b5ad6727cc9b0b9fdc",
"template_id": null
}
When status is done, all data has been downloaded and processed. This is when you should fetch verification reports.
Data object events: created
These events fire once per Link for each non-refresh Task completion, indicating that data objects have been successfully retrieved for the first time.
employment-created
An employment record has been discovered and extracted.
Additional fields:
| Field | Description |
|---|
object_id | The employment object identifier |
task_id | The associated Task |
tracking_info | Custom metadata (nullable) |
{
"webhook_id": "b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3",
"event_type": "employment-created",
"event_created_at": "2022-08-24T13:56:00.000000Z",
"updated_at": "2022-08-24T13:56:00.000000+00:00",
"object_id": "emp_obj_abc123",
"task_id": "521442a087604e599c637db310d07402",
"link_id": "d39d86dcc20c46e0ae75ba9ab1311a21",
"product": "employment",
"data_source": "payroll",
"tracking_info": null,
"user_id": "88fef4cea64c40b5ad6727cc9b0b9fdc",
"template_id": null
}
profile-created
User profile information has been extracted.
Additional fields: Same as employment-created (object_id, task_id, tracking_info).
statements-created
Pay statements have been retrieved. Fires once per Link for each non-refresh Task completion.
Additional fields:
| Field | Description |
|---|
employment_id | The associated employment record |
task_id | The associated Task |
objects_count | Number of statements retrieved |
{
"webhook_id": "c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4",
"event_type": "statements-created",
"event_created_at": "2022-08-24T13:57:00.000000Z",
"updated_at": "2022-08-24T13:57:00.000000+00:00",
"employment_id": "emp_obj_abc123",
"task_id": "521442a087604e599c637db310d07402",
"link_id": "d39d86dcc20c46e0ae75ba9ab1311a21",
"product": "income",
"data_source": "payroll",
"objects_count": 12,
"user_id": "88fef4cea64c40b5ad6727cc9b0b9fdc",
"template_id": null
}
shifts-created
Shift schedule data has been extracted.
Additional fields: Same as statements-created (employment_id, task_id, objects_count).
bank-accounts-created
Connected bank accounts have been discovered.
Additional fields: Same as statements-created (employment_id, task_id, objects_count).
Data object events: updated
These events fire after completing refresh Tasks. They only trigger when the objects_count value changes from the previous refresh. For example, if a person had 31 pay stubs and now has 32.
employment-updated
Employment data has been modified during a refresh.
Additional fields: Same as employment-created (object_id, task_id, tracking_info).
profile-updated
Profile information has changed during a refresh.
Additional fields: Same as employment-created (object_id, task_id, tracking_info).
statements-updated
New pay statements have been found during a refresh.
Additional fields: Same as statements-created (employment_id, task_id, objects_count).
shifts-updated
Shift data has changed during a refresh.
Additional fields: Same as statements-created (employment_id, task_id, objects_count).
bank-accounts-updated
Bank account data has changed during a refresh.
Additional fields: Same as statements-created (employment_id, task_id, objects_count).
Event summary
| Event | Trigger | Key Fields |
|---|
task-status-updated | Task status transitions | task_id, status, product, data_source |
employment-created | First employment extraction | object_id, task_id |
profile-created | First profile extraction | object_id, task_id |
statements-created | First statement retrieval | employment_id, objects_count |
shifts-created | First shift extraction | employment_id, objects_count |
bank-accounts-created | First bank account discovery | employment_id, objects_count |
employment-updated | Employment changed on refresh | object_id, task_id |
profile-updated | Profile changed on refresh | object_id, task_id |
statements-updated | New statements on refresh | employment_id, objects_count |
shifts-updated | Shifts changed on refresh | employment_id, objects_count |
bank-accounts-updated | Bank accounts changed on refresh | employment_id, objects_count |
