Implementation

Step 1: Enable Monitoring on Your Workspace

Please contact Pinwheel support so we can enable Monitoring for your workspace. Once enabled, Pinwheel will notify you of changes to payroll data for any supported accounts.

Step 2: Subscribe to Webhook Events

Whenever new data is available for a payroll account, the corresponding product webhook will be fired notifying you of that change. For example, if there is a change to the existing direct deposit allocations, you will receive a direct_deposit_allocations.added webhook. It is essential that you subscribe to webhooks in order to monitoring changes to payroll account data. Currently we ignore changes to whitespacing and character casing.

You can register a webhook endpoint for these events as described in Subscribing to Webhook Events.

Step 3: Retrieve New Account Data

Using account_id from the webhook event, make a request to the given product endpoint. For example, if you receive a direct_deposit_allocations.added webhook, you will then call the Get Direct Deposit Allocations to get the latest direct deposit allocations data for the account.

The field data.updated_at is a timestamp of when the data last changed. The field meta.refreshed_at is a timestamp of when the payroll provider was last queried for changes. Pinwheel always returns a snapshot of the latest data. To track these changes over time, you can store snapshots from Pinwheel when you receive them.

Step 4: Maintain Account Monitoring

Accounts can no longer be monitored due to various events such as session expiration, user settings changes, and platform updates. Pinwheel will send an account.monitoring_status.updated webhook event if our ability to monitor an account changes. To reconnect the account for Monitoring, you should have the user re-authenticate via Link. We retrieve new data immediately after users reestablish account monitoring so you can provide updated information to users quickly.

Subscribe to Account Monitoring Status Webhook Events

The monitoring_status field in the account.added webhook event will indicate if a payroll account supports the persistent connection for Monitoring.

The account.monitoring_status.updated webhook event will be sent if this state changes. For example, the user_action_required value indicates that an account requires On Demand Updates to be triggered to re-establish monitoring. See our On Demand Update guide for more detail.

You can register a webhook endpoint for these events as described in Subscribing to Webhook Events.

Re-Establish Monitoring

We're unable to retrieve data for an account that requires user action until the user has gone through Link again to reestablish monitoring.

You can initiate this user re-authentication flow in Link by creating a Link Token with the account_id field set. You should also provide org_name to personalize the Link flow for your brand. For example:

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "account_id": "account_id of the account to reestablish monitoring for"
}

Once launched, Link will ask the user for the minimal amount of information necessary to reestablish monitoring. For example, if the user only needs to complete multi-factor authentication, we will drop them directly into that portion of the flow.

You can also set skip_intro_screen: true to disable the introductory screen shown in Link. See Customization in the Implementation Guide for more info.

You'll get an onLogin callback and receive an account.monitoring_status.updated webhook event when monitoring is successfully reestablished. We'll immediately trigger data refresh jobs once the login completes to get you the latest account data.

Disable Monitoring for Individual Accounts

If you'd like to selectively disable all Monitoring for an individual account, use Disable Monitoring. Calling this will send an account.monitoring_status.updated webhook event with current_monitoring_status set to customer_disabled.

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