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.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 theaccounts.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.
- #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": true
will return the account object in the response within aresource
object.
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": true
will return the account object in the response within aresource
object.
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.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.
- #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.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.
- #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": true
will return the account object in the response within aresource
object.
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": true
will return the account object in the response within aresource
object.
- #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.
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_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:
- #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": true
will return the account object in the response within aresource
object.
- #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, thedetails
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
returnsfalse
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 asnull
. If the value ofallocation_id
isnull
, 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.
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": true
will return the account object in the response within aresource
object.
- #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.
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}