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
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.
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 }
}'
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)
{
"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
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
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.
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 }
}'
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)
{
"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
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
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.
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"
}'
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)
{
"event": "accounts.removed",
"name": "An account was removed",
"data": {
"account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
"user": "3823026e-a964-45f6-b201-6b8c096b30d3"
}
},
null,
2
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.
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 }
}'
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)
{
"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
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
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.
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 }
}'
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)
{
"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
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
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)
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 }
}'
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)
{
"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
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
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.
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 }
}'
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)
{
"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
