Webhooks
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 collectedpaystubs.thirty_days_synced
: Triggered when 30 days of paystubs have been collectedpaystubs.ninety_days_synced
: Triggered when 90 days of paystubs have been collectedpaystubs.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 collectedshifts.thirty_days_synced
: Triggered when 30 days of shifts have been collectedshifts.ninety_days_synced
: Triggered when 90 days of shifts have been collectedshifts.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.
Updated 8 days ago