Failed

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

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

Event

accounts.failed

Configuration

Attribute	Type	Description
include_resource	boolean optional	If set to `true` in the webhook subscription configuration, the webhook payload returns the full account object as `resource`. Defaults to `false`.

Payload

Attribute	Type	Description
account	string uuid	ID of the account.
user	string uuid	ID of the user associated with the account.
error_code	string	Error code that defines the reason the account failed to connect.
error_message	string	A longer text string associated with an `error_code` that explains why the error occurred.
resource	object	The full account object is returned if the webhook subscription contains `"include_resource": true` in the configuration.

Examples

curl -X POST https://api.argyle.com/v1/webhooks \
  -u api_key_id:api_key_secret \
  -H "Content-Type: application/json" \
  -d '{"events": ["accounts.failed"],
       "secret": "<secret for signature verification>",
         "name": "accounts.failed",
       "config": { "include_resource": true },
          "url": "https://webhook.site/url"}'

{
    "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"
            ],
            "..."
        }
    }
}