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
Implement the accounts.added webhook to know when a user connects via Argyle Link.
accounts.addedis 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.connectedor theaccounts.failedevent is triggered.accounts.connectedsignifies that an account was successfully authenticated with the correct credentials and a new account object was created.accounts.failedindicates that authentication failed when linking the account and that it was created with a failed authentication state.
- #eventsarray of stringsrequired
accounts.added - #namestringrequired
Your name for the webhook subscription.
- #urlstringrequired
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.
- #secretstringoptional
Optional secret used to verify webhooks.
- #configobjectoptional
"include_resource": truewill return the account object in the response within aresourceobject.
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 }'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
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.
- #eventsarray of stringsrequired
accounts.updated - #namestringrequired
Your name for the webhook subscription.
- #urlstringrequired
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.
- #secretstringoptional
Optional secret used to verify webhooks.
- #configobjectoptional
"include_resource": truewill return the account object in the response within aresourceobject.
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 }'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
Implement the accounts.removed webhook to know a user removes their account.
accounts.removedis 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.
- #eventsarray of stringsrequired
accounts.removed - #namestringrequired
Your name for the webhook subscription.
- #urlstringrequired
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.
- #secretstringoptional
Optional secret used to verify webhooks.
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 }'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
Implement the accounts.connected webhook to know when a user authenticates with Argyle Link.
accounts.connectedis triggered when a user successfully authenticates an account via Argyle Link.accounts.connectedis also triggered when the account is re-authenticated via Argyle Link for a second time, for example, due to the updated credentials.
- #eventsarray of stringsrequired
accounts.connected - #namestringrequired
Your name for the webhook subscription.
- #urlstringrequired
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.
- #secretstringoptional
Optional secret used to verify webhooks.
- #configobjectoptional
"include_resource": truewill return the account object in the response within aresourceobject.
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 }'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
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.
- #eventsarray of stringsrequired
accounts.failed - #namestringrequired
Your name for the webhook subscription.
- #urlstringrequired
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.
- #secretstringoptional
Optional secret used to verify webhooks.
- #configobjectoptional
"include_resource": truewill return the account object in the response within aresourceobject.
- #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_codethat explains why the error occurred. - #resourceobject
Contains the account object if
configwas included when subscribing to the webhook.
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 }'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
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_updatedwebhook 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_updatedwebhooks 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:
- #eventsarray of stringsrequired
accounts.pay_distribution_updated - #namestringrequired
Your name for the webhook subscription.
- #urlstringrequired
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.
- #secretstringoptional
Optional secret used to verify webhooks.
- #configobjectoptional
"include_resource": truewill return the account object in the response within aresourceobject.
- #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
nullin 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, thedetailsfield 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_changedreturnsfalsebecause 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_idfield returns asnull. If the value ofallocation_idisnull, the details field provides the reason why the updated allocation was not matched. - #resourceobject
Contains the account object if
configwas included when subscribing to the webhook.
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 }'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
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:
- #eventsarray of stringsrequired
accounts.pay_distribution_failed - #namestringrequired
Your name for the webhook subscription.
- #urlstringrequired
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.
- #secretstringoptional
Optional secret used to verify webhooks.
- #configobjectoptional
"include_resource": truewill return the account object in the response within aresourceobject.
- #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_codethat explains why the error occurred. - #resourceobject
Contains the account object if
configwas included when subscribing to the webhook.
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 }'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}