Introduction

Webhooks allow you to subscribe to server-side notifications of events, like completing jobs and newly available data. Webhooks are helpful to optimize your Pinwheel integration.

Subscribing to Webhook Events

You can register a webhook endpoint by sending a request to create a webhook specifying the events to subscribe to with the enabled_events parameter. You should explicitly enumerate the events you'd like to subscribe to (e.g., ['direct_deposit_switch.added', 'income.added']). Webhook endpoints must be https:// so that the event payloads can be transmitted securely.

POST /v1/webhooks
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET

{
  "url": "https://your-domain.com/webhook_endpoint",
  "status": "active",
  "enabled_events": [
    "direct_deposit_switch.added",
    "income.added"
  ]
}

Webhook Pause Policy

Webhook endpoints that fail to return a successful response code (200 OK) for 30 consecutive days will be set to status: paused to avoid unnecessary delivery attempts.

Webhook Quota

There is a quota of 10 registered webhooks per API key. Requests to create new webhooks after the quota has been reached will return an error response.

Webhook Event Handling

Webhook events are delivered over HTTPS to the endpoint you registered. An example event is:

POST /webhook-endpoint
Host: app.yourdomain.com
Content-Type: application/json
x-pinwheel-signature: v2=36a0c8d2049601b11290ebcae3348f627cba32889ca5ac3c8ff7ece1fef1ad8f
x-pinwheel-webhook-id: 61788409-8314-4e89-9300-ae7b9d3ccff5
x-timestamp: 1609205925

{
  "event": "direct_deposit_switch.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    ...
  }
}

Verifying Pinwheel is the Sender

Pinwheel signs all webhook events it sends to your endpoints by including a signature in each event's x-pinwheel-signature header. You can use this signature to verify that the events were sent by Pinwheel, not by a third party. Learn more at Webhook Signature Verification.

Retry Policy

Pinwheel expects a response within 15 seconds from your endpoint. Pinwheel will redeliver a webhook event if your webhook endpoint returns a failure (5XX status codes or network issues). Up to 5 subsequent delivery attempts will be made with exponential backoff including jitter in the 15 minutes following the initial delivery attempt.

Handling Duplicate Events

The event_id request body parameter is unique for each webhook event. This can be used to guard against potential duplicate events and make your system idempotent. It can also be used to troubleshoot webhook event specific issues, so we recommend logging this identifier.

Webhook events are delivered with "at least once" guarantees, meaning that (rarely) the same webhook event will be delivered to your system multiple times.

Webhook Request Body

All webhook requests have a JSON body with the following parameters:

Param	Type	Description
`event`	string	Webhook event, e.g., `direct_deposit_switch.added`.
`event_id`	string	Unique ID for each webhook event.
`payload`	object	Payload attributes vary based on event.

Webhook Request Headers

All webhook requests have the following headers:

Header	Type	Description
`x-pinwheel-signature`	string	See Webhook Signature Verification.
`x-pinwheel-webhook-id`	string	ID of the webhook created via the POST /webhooks endpoint.
`x-timestamp`	integer	When the request was sent in Unix epoch time seconds.

Pending Webhook Job Outcomes

All job-associated webhook events include an outcome in the payload. The outcome represents the status of a job, and it can be either success, error, or pending. A pending status indicates that a job was unable to be completed on its first attempt and will be retried up to 24 hours after the initial attempt. A job with a pending status will transition to either an error or a success within the 24-hour window, and you will be notified with another webhook event.

Webhook Events

Account Webhook Events

account.added

User successfully logs into their payroll accounts. This webhook correlates to the onLogin callback.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when creating the Link token, if provided.
`link_token_id`	string	UUID of the Link token used to initialize Link.
`platform_id`	string	UUID of the payroll platform associated with this account.
`platform_name`	string	The name of the payroll platform associated with this account.
`created_at`	string	ISO 8601 timestamp of payroll account creation.
`connected`	boolean	If set to true, you can retrieve new information for the account on a recurring basis.
`monitoring_status`	string	Describes the automated ability of Pinwheel to retrieve new account information. See account.monitoring_status.updated for possible values.

Sample Webhook Event

{
  "event": "account.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
    "end_user_id": "my_user_12345",
    "link_token_id": "7c4ac4be-4a0e-4468-ab26-c42b249b233b",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
    "platform_name": "Justworks",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true,
    "monitoring_status": "active"
  }
}

account.additional_connections_recommended

This webhook event evaluates the data retrieved from the payroll account to determine if another account (e.g., a T&A account) could provide additional data and provides a suggested action to take.

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the payroll account.
`end_user_id`	string	The user identifier you specified when creating the Link token, if provided.
`additional_connections`	array	A list of platform connection recommendations.
`additional_connections.platform_type`	string	The type of the platform this recommendation is for. Currently, only supports "time_and_attendance".
`additional_connections.action`	string	One of `none`, `login`, `search`, or `ask`.
`additional_connections.platform_id` (optional)	string	UUID of the recommended platform, if we recommended connecting to it (i.e., action is `login`).
`link_token_id`	string	UUID of the Link token used to initialize Link.

Sample Webhook Event

{
  "event": "account.additional_connections_recommended",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
    "end_user_id": "my_user_12345",
    "link_token_id": "158dc949-84a3-4c81-bf7f-2977b4d70048",
    "additional_connections": [
        {
            "platform_type": "time_and_attendance",
            "action": "login",
            "platform_id": "7ceec993-c958-4b90-b419-fda2506b612d"
        }
    ]
  }
}

account.monitoring_status.updated

Pinwheel's ability to monitor a payroll account has changed. See Recurring Access for more info.

Several monitoring statuses are possible:

monitoring_status	Description
`active`	Pinwheel is monitoring for data changes daily.
`degraded`	Pinwheel is trying to monitor but seeing spurious errors and may be unable to return data for the time being. You may want to use this to inform users about laggy data.
`user_action_required`	You need to use On Demand Updates to have a user re-complete the login process.
`unavailable`	Pinwheel doesn’t support monitoring for this account.
`customer_disabled`	You used `POST /v1/accounts/{id}/disable_monitoring` to manually turn off monitoring.

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 account, if provided.
`updated_at`	string	ISO 8601 timestamp of when Pinwheel updated the monitoring_status for this account.
`current_monitoring_status`	string	The latest monitoring status for the account. See the table above for a set of possible values.

Sample Webhook Event

{
  "event": "account.monitoring_status.updated",
  "event_id": "5a141122-4235-4fa1-bd76-0123456780b0",
  "payload": {
    "current_monitoring_status": "active",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "updated_at": "2021-01-12T02:36:01.287148+00:00"
  }
}

Direct Deposit Webhook Events

Direct Deposit webhook events will notify you when new direct deposit allocation data is available for a payroll account or a direct deposit job completed.

direct_deposit_allocations.added

Direct deposit allocations data is now available for the payroll account.

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.
`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": "direct_deposit_allocations.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": "direct_deposit_allocations",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success"
  }
}

direct_deposit_switch.added

A direct_deposit_switch job to add a new direct deposit allocation completed.

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.
`params` (optional)	object	Parameters of the job, if applicable.
`params.action`	string	Indicates whether the `direct_deposit_switch` was a `full_switch` or a `partial_switch`.
`params.allocation` (optional)	object	The allocation that was created/updated during a `direct_deposit_switch`. Only present when `params.action` is `partial_switch`
`params.allocation.type` (optional)	string	Indicates whether this is a `remainder`, `amount` or `percentage` allocation. Will be set if `params.action` is `partial_switch`.
`params.allocation.value` (optional)	integer	The value (if any) for this allocation. Will be set if the type is `percentage` or `amount`.
`params.allocation.target.account_name` (optional)	string	The account name (if any) for this allocation. We recommending including `name` during link token creation if you send multiple accounts.
`params.allocation.target.account_type`	string	The account type for this allocation. Will be either `checking` or `savings`.
`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.
`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

A partial amount switch creates a fixed-amount allocation on the payroll account.
A partial percentage switch creates a percentage-based allocation on the payroll account.
A remainder switch replaces the existing remainder allocation on a payroll account and leaves existing allocations unaffected.

{
  "event": "direct_deposit_switch.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": "direct_deposit_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "action": "partial_switch",
      "allocation": {
        "type": "amount",
        "value": 5400,
        "target": {
          "account_name": "My Checking Account",
          "account_type": "checking"
        }
      }
    }
  }
}

{
  "event": "direct_deposit_switch.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": "direct_deposit_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "action": "partial_switch",
      "allocation": {
        "type": "percentage",
        "value": 33,
        "target": {
          "account_name": "My Checking Account",
          "account_type": "checking"
        }
      }
    }
  }
}

{
  "event": "direct_deposit_switch.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": "direct_deposit_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "action": "partial_switch",
      "allocation": {
        "type": "remainder",
        "target": {
          "account_name": "My Checking Account",
          "account_type": "checking"
        }
      }
    }
  }
}

{
  "event": "direct_deposit_switch.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": "direct_deposit_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "action": "full_switch",
      "allocation": {
        "target": {
          "account_name": "My Checking Account",
          "account_type": "checking"
        }
      }
    }
  }
}

Income & Employment Webhooks

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

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
    }
  }
}

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

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

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

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

Tax Forms Webhooks

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

Earnings Stream Webhooks

Earnings Stream webhook events will notify you when a newer version of the Earnings Stream is available for a user. See Earnings Stream Webhook Events for more details.

Please contact [email protected] for access to our Developer Dashboard.