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 to 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. Thetype
field in the webhook’s payload returnsbank_account
orcard
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:
Event
accounts.pay_distribution_updated
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 where the direct deposit update was successful. |
user | string uuid | ID of the user associated with the account. |
resource | object | The full account object is returned if the webhook subscription contains "include_resource": true in the configuration. |
allocation_id | string 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, the details field provides the reason why the updated allocation was not matched. |
pay_distribution_changed | boolean | 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 returns false because no details were changed. |
type | string enum | Denotes the type of allocation that was updated. Possible values: bank_account , card |
flow | string enum | Denotes the type of direct deposit flow that triggered the update. Possible values: - update - there was an update to the direct deposit.- removal - a deposit account was removed.- activation *deprecated - a pay allocation becomes active after a microdeposit verification. |
details | string 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 as null . If the value of allocation_id is null , the details field provides the reason why the updated allocation was not matched.Possible values: - obfuscated - the exact allocation_id cannot be determined because the payroll provider obfuscates bank account or card details.- multiple_matching_allocations - the exact allocation_id cannot be determined because there are multiple allocations with partially matching bank account or card details used in the DDS configuration. |
When allocation_id
cannot be matched
allocation_id
cannot be matchedIn this example, due the partially matching bank account details in bank_account_A
and bank_account_B
, it is not possible to match the updated pay allocation to any of the user's bank accounts or cards with total accuracy. In this case, allocation_id
returns null
and details
returns multiple_matching_allocations
.
{
"bank_account_A": {
"routing_number": "*****1234",
"account_number": "*********5678",
"account_type": "savings"
},
"bank_account_B": {
"routing_number": "*****1234",
"account_number": "*********5678",
"account_type": "savings"
}
}
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.pay_distribution_updated"],
"secret": "<secret for signature verification>",
"name": "accounts.pay_distribution_updated",
"config": { "include_resource": true },
"url": "https://webhook.site/url"}'
{
"event": "accounts.pay_distribution_updated",
"name": "Pay distribution updated successfully",
"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"
],
"..."
},
"allocation_id": "4334r6e-a964-45eef6-b201-64464",
"pay_distribution_changed": true,
"type": "bank_account",
"details": null,
"flow": "update"
}
}