Balance Update Webhook and Endpoint
The Balance Update Endpoint is required for sending outbound ACH transfers from your client, as it enables Astra to fetch the balance of the end-user's account created through account number and routing number via the POST /v1/accounts/create endpoint.
The balance_update
webhook type tells Astra to update the balance of this account created through account number and routing number (where there is not a Plaid connection to leverage). This also allows your application to utilize more advanced Routines like the refill
type, but is not required for one-time Routines.
We recommend authenticating the endpoint using two keys (one private (provided by you), one public (provided by Astra) and encoding the keys using HMAC-SHA256 (hex). Astra will provide the public key and the HMAC-generated key signature in the request headers like so (--header "Astra-Key-Signature: < encoded key signature >" --header "Astra-Public-Key: < a custom public key provided by Astra >"). You should provide the โAstra-Private-Keyโ and an account ID for testing in sandbox.
Data Lifecycle Overview
- An event triggers a change in the balance for your User's account
- Your application fires a balance_updated webhook
- Astra GETs the balance data from your application by Account ID
- If the balance data of the account is the trigger of a Routine or your User's account is the source, Astra will initiate a transfer
Data Lifecycle Details
Step 2: Your application fires a balance_updated webhook
Sandbox: https://api-sandbox.astra.finance/v1/webhook/customer_event
Production: https://api.astra.finance/v1/webhook/customer_event
Webhook Payload:
{
"institution_id": "astra_ins_001", //your institution id
"resource_id": "astra_account_id_goes_here",
"event_type": "balance_update"
}
Step 3: Astra GETs the balance data from your application by account ID
https://yourapp.com/astra/balance
Astra will need an endpoint to call to get the balance of an account after receiving a balance_update
webhook. We recommend the following:
- The endpoint should be secure and utilize authentication. Usually a combination of basic auth and JWT (with an expiration)
- The endpoint should accept an
account_id
parameter - The endpoint should return a JSON response with the following payload:
- Both available_balance and current_balance are required
- Balances should be integers (cents)
{ "available_balance": 12345, "current_balance": 12345 }