Tax Forms Webhook Events

Tax forms webhook events will notify you when new tax forms data is available for a payroll account or a tax forms job completed.

tax_forms.added

Tax forms data for the payroll account is available. Use account_id in the payload to query the Get Tax Form 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 `tax_forms`.
`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.
`added`	array	A list of objects specifying ID, year, and form type of the new tax forms that were added to the payroll account.
`deleted`	array	A list of objects specifying ID, year, and form type of the old tax forms that were removed from the payroll account.
`id`	string	Deprecated. UUID of the job. You should use `account_id` as the main identifier.

Sample Webhook Event

{
    "event": "tax_forms.added",
    "event_id": "9bb2d0cd-9f54-4829-a6c2-a48b0cd18b6d",
    "payload": {
        "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
        "end_user_id": "01234",
        "link_token_id": "f2b2cc6e-b53c-4175-9319-acfc3f39f9f2",
        "name": "tax_forms",
        "timestamp": "2021-01-12T02:36:01.287148+00:00",
        "outcome": "success",
        "added": [{
            "id": "b0e92f7b-c0b2-4418-a34d-3f316ca45c84",
            "year": 2022,
            "form_type": "W-2"
        }],
        "deleted": [{
            "id": "57043868-6fb3-47e8-a2b7-c993bd023f25",
            "year": 2001,
            "form_type": "1099-K"
        }]
    }
}