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

## 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 Event Handling

Webhook events are delivered over HTTPS to the endpoint you registered. An example event is:

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

## Webhook Request Headers

All webhook requests have the following headers:

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

#### Sample Webhook Event

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

See [Supplement Shifts with T&A Platforms](🔗) for more information on how to work with the recommendations provided by this webhook event.

#### Payload Schema

#### Sample Webhook Event

### account.monitoring_status.updated

Pinwheel's ability to monitor a payroll account has changed (i.e. [DDA](🔗) and [I&E](🔗)).

Several monitoring statuses are possible:

#### Payload Schema

#### Sample Webhook Event

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

#### Sample Webhook Event

### direct_deposit_switch.added

A `direct_deposit_switch` job to add a new direct deposit allocation completed.

We are currently in the process of updating this webhook to the new structure outlined below. This change will be rolled out on 8/1, but you may opt-in to it at an earlier time. To view the old structure, scroll down to the next section below.

##### Payload Schema

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

#### To be deprecated on 8/1/22

Previously, `params.amount` was used to represent the amount of the new direct deposit allocation. We will be deprecating this key on 8/1 in favor of the new structure outlined above, but you can upgrade at any time by reaching out to us.

##### Sample Webhook Event

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

#### Sample Webhook Event

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

#### Sample Webhook Event

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

#### Sample Webhook Event

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

#### Sample Webhook Event

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

• `paystubs.thirty_days_synced`: Triggered when 30 days of paystubs have been collected

• `paystubs.ninety_days_synced`: Triggered when 90 days of paystubs have been collected

• `paystubs.fully_synced`: Triggered when all available paystubs have been collected

##### Payload Schema

##### Sample Webhook Events

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

#### Sample Webhook Event

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

• `shifts.thirty_days_synced`: Triggered when 30 days of shifts have been collected

• `shifts.ninety_days_synced`: Triggered when 90 days of shifts have been collected

• `shifts.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

##### Sample Webhook Event

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