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

  1. An event triggers a change in the balance for your User's account
  2. Your application fires a balance_updated webhook
  3. Astra GETs the balance data from your application by Account ID
  4. 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
}