> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Accounts Webhooks

> Learn about accounts webhooks.

Accounts webhooks notify your system when new [accounts](/legacy/api-reference/accounts) are added or existing accounts are either **updated** or **removed**, or if an authentication attempt is successful and the account is **connected** or if the authentication attempt **failed** and the account is created with a failed authentication state.

## Added

**POST** `/v1/webhooks`

Implement the `accounts.added` webhook to know when a user connects via Argyle Link.

* `accounts.added` is triggered the moment a user initiates a new connection via Argyle Link by submitting their login credentials.
* After an account is created, either the `accounts.connected` or the `accounts.failed` event is triggered.
* `accounts.connected` signifies that an account was successfully authenticated with the correct credentials and a new [account object](/legacy/api-reference/accounts#account-object) was created.
* `accounts.failed` indicates that authentication failed when linking the account and that it was created with a failed authentication state.

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["accounts.added"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["accounts.added"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "accounts.added",
"name": "An account was created",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"resource": {
"id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"employers": [
"homedepot"
],
"...": "..."
}
}
},
null,
2

```

<RefSubLayout.Divider />

## Updated

**POST** `/v1/webhooks`

Implement the `accounts.updated` webhook to know when account data changes.

* accounts.updated is triggered when there is any change in data associated with the account. Any new data, status, or timestamp update associated with the [account object](/legacy/api-reference/accounts#account-object) will trigger this webhook.
* accounts.updated fires at the same time as accounts.failed and accounts.connected, since both of these webhooks are associated with a status change in the account object.

<Note>
  When a payroll account is connected for the first time, updates can be frequent because the account is constantly updated during the initial scan. There are fewer updates once the initial scan finishes. From that point on, updates are only triggered by periodic scans that occur every few hours.
</Note>

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["accounts.updated"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["accounts.updated"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "accounts.updated",
"name": "An account was updated",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"resource": {
"id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"employers": [
"homedepot"
],
"...": "..."
}
}
},
null,
2

```

<RefSubLayout.Divider />

## Removed

**POST** `/v1/webhooks`

Implement the `accounts.removed` webhook to know a user removes their account.

* `accounts.removed` is triggered when an account is removed. This happens when a user request through Argyle Link or when the API is called on the [account object](/legacy/api-reference/accounts#account-object).

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["accounts.removed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["accounts.removed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret"
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "accounts.removed",
"name": "An account was removed",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3"
}
},
null,
2

```

<RefSubLayout.Divider />

## Connected

**POST** `/v1/webhooks`

Implement the `accounts.connected` webhook to know when a user authenticates with Argyle Link.

* `accounts.connected` is triggered when a user successfully authenticates an account via Argyle Link.
* `accounts.connected` is also triggered when the account is re-authenticated via Argyle Link for a second time, for example, due to the updated credentials.

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["accounts.connected"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["accounts.connected"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "accounts.connected",
"name": "An account was connected",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"resource": {
"id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"employers": [
"homedepot"
],
"...": "..."
}
}
},
null,
2

```

<RefSubLayout.Divider />

## Failed

**POST** `/v1/webhooks`

Implement the `accounts.failed` webhook to know when an account fails to authenticate.

accounts.failed is triggered when:

* A user unsuccessfully tries to authenticate an account via Argyle Link.
* There is a repeated unsuccessful re-authentication attempt via Argyle Link, for example, due to mistyped updated credentials.
* The MFA times out.

`accounts.failed` is **not** triggered if the account authentication expires or the credentials are changed (for example, the user changes their password to the payroll provider's system). It only triggers when there is an unsuccessful authentication attempt via Argyle Link. To stay updated regarding expired authentication or disconnections due to changed credentials, use the `accounts.updated` webhook. The `connection.status` of the [account object](/legacy/api-reference/accounts#account-object) changing to `error` (with an `auth_required` error message) will be what triggers the `accounts.updated` webhook in these situations.

When a user submits incorrect authentication details, the `accounts.failed` webhook is triggered. The details can include username and password and various types of multi factor authentication challenges. An unsuccessful attempt still creates an account object, in a failed auth state. Such accounts can be removed with a [DELETE call to the API](/legacy/api-reference/accounts#delete) if not needed.

Visit [Account connection errors](/legacy/guides/troubleshooting/account-connection-errors) to see which specific errors trigger this webhook.

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.
* `error_code` (string, optional): Error code that defines the reason the account failed to connect.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["accounts.failed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["accounts.failed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "accounts.failed",
"name": "An account failed to authenticate",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"error_code": "invalid_mfa",
"error_message": "This user did not provide the correct multi-factor authentication response.",
"resource": {
"id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"employers": [
"homedepot"
],
"...": "..."
}
}
},
null,
2

```

<RefSubLayout.Divider />

## Pay Distribution updated

**POST** `/v1/webhooks`

Implement the `accounts.pay_distribution_updated` webhook to know when a direct deposit switching flow is successful.

The `accounts.pay_distribution_updated` webhook is triggered after:

* You request a direct deposit update.
* Your user confirms this update.
* Argyle updates the direct deposit successfully.

This webhook notifies you when the direct deposit update is successful. Depending on your DDS configuration, this is what the webhook returns:

* If the DDS configuration is for a single allocation type that is either a bank account or a card, a single `accounts.pay_distribution_updated` webhook is triggered. The type field in the webhook's payload returns bank\_account or card accordingly.
* If the DDS configuration has both a bank account and a card, two separate `accounts.pay_distribution_updated` webhooks are triggered with corresponding payloads for each allocation type.

<Note>
  `pay_allocations` [webhooks](/legacy/api-reference/pay-allocations-webhooks) are fired after a successful direct deposit update as well, but they can also trigger during periodic scans if something on the payroll provider's side changes or the user independently updates their pay allocations. <br /><br />*We recommend using `accounts.pay_distribution_updated` to track direct deposit changes you initiate for the user.* <br /><br />A payroll account can allocate a paycheck to multiple accounts. Pay distribution webhooks will fire if any changes are made to any of these paycheck allocations. To monitor if a pay allocation to an individual account changes, set up webhooks for pay allocations, using these pages:

  * [Pay allocations added](/legacy/api-reference/pay-allocations-webhooks#added)
  * [Pay allocations updated](/legacy/api-reference/pay-allocations-webhooks#updated)
  * [Pay allocations removed](/legacy/api-reference/pay-allocations-webhooks#removed)
</Note>

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.
* `pay_distribution_changed` (boolean, optional)
* `flow` (note, optional)
* `details` (note, optional)

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["accounts.pay_distribution_updated"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["accounts.pay_distribution_updated"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "accounts.pay_distribution_updated",
"name": "Pay distribution updated successfully",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"allocation_id": "4334r6e-a964-45eef6-b201-64464",
"pay_distribution_changed": true,
"type": "bank_account",
"flow": "update",
"details": null,
"resource": {
"id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"employers": [
"homedepot"
],
"...": "..."
}
}
},
null,
2

```

<RefSubLayout.Divider />

## Pay Distribution failed

**POST** `/v1/webhooks`

Implement the `accounts.pay_distribution_failed` webhook to know when a pay distribution update fails.

`accounts.pay_distribution_failed` is triggered when a direct deposit flow could not be completed and the update is not successful.

<Note>
  A payroll account can allocate a paycheck to multiple accounts. Pay distribution webhooks will fire if any changes are made to any of these paycheck allocations. To monitor if a pay allocation to an individual account changes, set up webhooks for pay allocations, using these pages:

  * [Pay allocations added](/legacy/api-reference/pay-allocations-webhooks#added)
  * [Pay allocations updated](/legacy/api-reference/pay-allocations-webhooks#updated)
  * [Pay allocations removed](/legacy/api-reference/pay-allocations-webhooks#removed)
</Note>

### Request body

### Webhook message

* `name` (string, optional): Name used for the webhook subscription.
* `data` (object, optional)
* `account` (string (uuid), optional): ID of the account.
* `user` (string (uuid), optional): ID of the user.
* `error_code` (string, optional): Error code that defines the reason the direct deposit update failed.

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request POST \\
    --url https://api.argyle.com/v1/webhooks \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json' \\
    --data '{
    "events": ["accounts.pay_distribution_failed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }'
    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/webhooks"
    payload = {
    "events": ["accounts.pay_distribution_failed"],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",
    "config": { "include_resource": true }
    }
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.post(url, json=payload, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

{
"event": "accounts.pay_distribution_failed",
"name": "A pay distribution failed to update",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"error_code": "invalid_mfa",
"error_message": "This user did not provide the correct multi-factor authentication response.",
"resource": {
"id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3",
"employers": [
"homedepot"
],
"...": "..."
}
}
},
null,
2

```