GuidesAPI ReferenceChangelog
Log In

# 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:

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.

Example Link flow from intro screen, to reconnecting screen, to an MFA screen.

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](🔗).