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