Accounts Webhooks

Learn about accounts webhooks.

Accounts webhooks notify your system when new 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 was created.
- accounts.failed indicates that authentication failed when linking the account and that it was created with a failed authentication state.

Request body

#
eventsarray of strings
required
accounts.added
#
namestring
required
Your name for the webhook subscription.
#
urlstring
required
Where you want to receive webhook delivery. This can be either a backend URL that you manage, or a URL provided by a webhook management service.
#
secretstring
optional
Optional secret used to verify webhooks.
#
configobject
optional
"include_resource": true will return the account object in the response within a resource object.

Webhook message

#
eventstring
accounts.added
#
namestring
Name used for the webhook subscription.
#
dataobject
#
accountstring (uuid)
ID of the account.
#
userstring (uuid)
ID of the user.
#
resourceobject
Contains the account object if config was included when subscribing to the webhook.

Example Subscription

1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["accounts.added"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret",
10        "config": { "include_resource": true }
11     }'

Example Webhook

1{
2  "event": "accounts.added",
3  "name": "An account was created",
4  "data": {
5    "account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
6    "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
7    "resource": {
8      "id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
9      "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
10      "employers": [
11        "homedepot"
12      ],
13      "...": "..."
14    }
15  }
16}

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

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.

Request body

#
eventsarray of strings
required
accounts.updated
#
namestring
required
Your name for the webhook subscription.
#
urlstring
required
Where you want to receive webhook delivery. This can be either a backend URL that you manage, or a URL provided by a webhook management service.
#
secretstring
optional
Optional secret used to verify webhooks.
#
configobject
optional
"include_resource": true will return the account object in the response within a resource object.

Webhook message

#
eventstring
accounts.updated
#
namestring
Name used for the webhook subscription.
#
dataobject
#
accountstring (uuid)
ID of the account.
#
userstring (uuid)
ID of the user.
#
resourceobject
Contains the account object if config was included when subscribing to the webhook.

Example Subscription

1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["accounts.updated"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret",
10        "config": { "include_resource": true }
11     }'

Example Webhook

1{
2  "event": "accounts.updated",
3  "name": "An account was updated",
4  "data": {
5    "account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
6    "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
7    "resource": {
8      "id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
9      "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
10      "employers": [
11        "homedepot"
12      ],
13      "...": "..."
14    }
15  }
16}

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

Request body

#
eventsarray of strings
required
accounts.removed
#
namestring
required
Your name for the webhook subscription.
#
urlstring
required
Where you want to receive webhook delivery. This can be either a backend URL that you manage, or a URL provided by a webhook management service.
#
secretstring
optional
Optional secret used to verify webhooks.

Webhook message

#
eventstring
accounts.removed
#
namestring
Name used for the webhook subscription.
#
dataobject
#
accountstring (uuid)
ID of the account.
#
userstring (uuid)
ID of the user.

Example Subscription

1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["accounts.removed"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret"
10     }'

Example Webhook

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

#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

#
eventsarray of strings
required
accounts.connected
#
namestring
required
Your name for the webhook subscription.
#
urlstring
required
Where you want to receive webhook delivery. This can be either a backend URL that you manage, or a URL provided by a webhook management service.
#
secretstring
optional
Optional secret used to verify webhooks.
#
configobject
optional
"include_resource": true will return the account object in the response within a resource object.

Webhook message

#
eventstring
accounts.connected
#
namestring
Name used for the webhook subscription.
#
dataobject
#
accountstring (uuid)
ID of the account.
#
userstring (uuid)
ID of the user.
#
resourceobject
Contains the account object if config was included when subscribing to the webhook.

Example Subscription

1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["accounts.connected"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret",
10        "config": { "include_resource": true }
11     }'

Example Webhook

1{
2  "event": "accounts.connected",
3  "name": "An account was connected",
4  "data": {
5    "account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
6    "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
7    "resource": {
8      "id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
9      "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
10      "employers": [
11        "homedepot"
12      ],
13      "...": "..."
14    }
15  }
16}

#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 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 if not needed.

Visit Account connection errors to see which specific errors trigger this webhook.

Request body

#
eventsarray of strings
required
accounts.failed
#
namestring
required
Your name for the webhook subscription.
#
urlstring
required
Where you want to receive webhook delivery. This can be either a backend URL that you manage, or a URL provided by a webhook management service.
#
secretstring
optional
Optional secret used to verify webhooks.
#
configobject
optional
"include_resource": true will return the account object in the response within a resource object.

Webhook message

#
eventstring
accounts.failed
#
namestring
Name used for the webhook subscription.
#
dataobject
#
accountstring (uuid)
ID of the account.
#
userstring (uuid)
ID of the user.
#
error_codestring
Error code that defines the reason the account failed to connect.
#
error_messagestring
A longer text string associated with an error_code that explains why the error occurred.
#
resourceobject
Contains the account object if config was included when subscribing to the webhook.

Example Subscription

1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["accounts.failed"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret",
10        "config": { "include_resource": true }
11     }'

Example Webhook

1{
2  "event": "accounts.failed",
3  "name": "An account failed to authenticate",
4  "data": {
5    "account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
6    "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
7    "error_code": "invalid_mfa",
8    "error_message": "This user did not provide the correct multi-factor authentication response.",
9    "resource": {
10      "id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
11      "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
12      "employers": [
13        "homedepot"
14      ],
15      "...": "..."
16    }
17  }
18}

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

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.

We recommend using accounts.pay_distribution_updated to track direct deposit changes you initiate for the user.

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:

Request body

#
eventsarray of strings
required
accounts.pay_distribution_updated
#
namestring
required
Your name for the webhook subscription.
#
urlstring
required
Where you want to receive webhook delivery. This can be either a backend URL that you manage, or a URL provided by a webhook management service.
#
secretstring
optional
Optional secret used to verify webhooks.
#
configobject
optional
"include_resource": true will return the account object in the response within a resource object.

Webhook message

#
eventstring
accounts.pay_distribution_updated
#
namestring
Name used for the webhook subscription.
#
dataobject
#
accountstring (uuid)
ID of the account.
#
userstring (uuid)
ID of the user.
#
allocation_idstring (uuid)
ID of the pay allocation passed in the pay distribution config. The value is null in some edge cases where it is not possible to match the updated pay allocation to any of the user's bank accounts or cards with total accuracy. In such cases, the details field provides the reason why the updated allocation was not matched.
#
pay_distribution_changedboolean
Indicates whether a successful direct deposit update has resulted in any changes in the user's pay allocation details.

For example, when a successful direct deposit update was created using the same pay allocation details that were already present on the user's payroll account, pay_distribution_changed returns false because no details were changed.
#
typestring (enum)
Denotes the type of allocation that was updated.
#
flowstring (enum)
Denotes the type of direct deposit flow that triggered the update.
#
detailsstring (enum)
In some edge cases where it is not possible to match the updated pay allocation to any of the user's bank accounts or cards with total accuracy, the value of the allocation_id field returns as null. If the value of allocation_id is null, the details field provides the reason why the updated allocation was not matched.
#
resourceobject
Contains the account object if config was included when subscribing to the webhook.

Example Subscription

1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["accounts.pay_distribution_updated"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret",
10        "config": { "include_resource": true }
11     }'

Example Webhook

1{
2  "event": "accounts.pay_distribution_updated",
3  "name": "Pay distribution updated successfully",
4  "data": {
5    "account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
6    "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
7    "allocation_id": "4334r6e-a964-45eef6-b201-64464",
8    "pay_distribution_changed": true,
9    "type": "bank_account",
10    "flow": "update",
11    "details": null,
12    "resource": {
13      "id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
14      "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
15      "employers": [
16        "homedepot"
17      ],
18      "...": "..."
19    }
20  }
21}

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

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:

Request body

#
eventsarray of strings
required
accounts.pay_distribution_failed
#
namestring
required
Your name for the webhook subscription.
#
urlstring
required
Where you want to receive webhook delivery. This can be either a backend URL that you manage, or a URL provided by a webhook management service.
#
secretstring
optional
Optional secret used to verify webhooks.
#
configobject
optional
"include_resource": true will return the account object in the response within a resource object.

Webhook message

#
eventstring
accounts.pay_distribution_failed
#
namestring
Name used for the webhook subscription.
#
dataobject
#
accountstring (uuid)
ID of the account.
#
userstring (uuid)
ID of the user.
#
error_codestring
Error code that defines the reason the direct deposit update failed.
#
error_messagestring
A longer text string associated with an error_code that explains why the error occurred.
#
resourceobject
Contains the account object if config was included when subscribing to the webhook.

Example Subscription

1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["accounts.pay_distribution_failed"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret",
10        "config": { "include_resource": true }
11     }'

Example Webhook

1{
2  "event": "accounts.pay_distribution_failed",
3  "name": "A pay distribution failed to update",
4  "data": {
5    "account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
6    "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
7    "error_code": "invalid_mfa",
8    "error_message": "This user did not provide the correct multi-factor authentication response.",
9    "resource": {
10      "id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
11      "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
12      "employers": [
13        "homedepot"
14      ],
15      "...": "..."
16    }
17  }
18}

Users

User Invites

Accounts

Link Items

Webhooks

Profiles

Employments

Income Totals

Payouts

Documents

Reports

Forms

Activities

Reputations

Vehicles

Pay Allocations

DDS Configurations

Users

Accounts

Profiles

Employments

Payouts

Documents

Forms

Activities

Reputations

Vehicles

Pay Allocations

Accounts Webhooks

#Added

#Updated

#Removed

#Connected

#Failed

#Pay Distribution updated

#Pay Distribution failed

Data Structure

Flows

Management

Reference

POS & LOS Systems

Day 1 Certainty® and AIM

Document Processing

Verification of Income and Employment

Deposit Switching

Paycheck-linked Lending

Getting Started

Argyle Link

Argyle Console

Troubleshooting

Accounts Webhooks

#Added

#Updated

#Removed

#Connected

#Failed

#Pay Distribution updated

Possible values:

Possible values:

Possible values:

#Pay Distribution failed