Account Webhook Events

Account webhooks notify you when an account has been created, and when an account's monitoring status has been updated.

account.added

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

Payload Schema

Payload Param	Type	Description
`account_id`	string	UUID of the account the user has successfully logged into.
`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 platform associated with this account.
`platform_name`	string	The name of the platform associated with this account.
`platform_type`	string	The type of the platform. `payroll` platforms are used for direct-deposit switching and for Verify use cases. `time_and_attendance` platforms contain data around shifts and hours. `tax` platforms are used for tax solutions. `merchant` type platforms are used for bill switching and cancellation.
`reported_platform_name` (optional)	string	If the user attempts a bill switch/cancellation against a merchant we don't track, the `platform_name` will be "Other (merchant)" and this field will contain the reported name of the merchant.
`reserved_platform_id` (optional)	string	Similar to `reported_platform_name`, this field holds the UUID of the merchant/platform if we add it in the future.
`created_at`	string	ISO 8601 timestamp of 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 - login to payroll platform

{
  "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",
    "platform_type": "payroll",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true,
    "monitoring_status": "active"
  }
}

Sample Webhook Event - user logs in to untracked merchant platform

{
  "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": "0cc073dc-f3f7-4a9e-a287-fb34a43cb71e",
    "platform_name": "Other (merchant)",
    "platform_type": "merchant",
    "reported_platform_name": "Smalltown Life Insurance Co",
    "reserved_platform_id": "5d426d0e-0618-46ea-945a-b8ca679ac39f",
    "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 a 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"
  }
}