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. It only triggers when there is an unsuccessful authentication attempt.
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.
Event
accounts.failed
Configuration
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
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"
],
...
}
}
}