Spending Goal Progress, Reached and Exceeded

Id: spendingGoalProgress, spendingGoalReached, spendingGoalExceeded

Webhook events that notify when a user's spending progress against their defined spending goals reaches certain thresholds (25%, 50%, 75%, 100%, and when exceeding the goal). The webhook is triggered when new transactions are synchronised and the calculated progress crosses one of these warning levels within the user's current budget period.

When it is sent

Account sync completes successfully with new transactions added
User has active spending goals for the current budget period
Spending progress crosses warning level thresholds:
- 25%, 50%, 75% of goal amount (triggers spendingGoalProgress)
- Exactly 100% of goal amount (triggers spendingGoalReached)
- Over 100% of goal amount (triggers spendingGoalExceeded)
Progress calculation: (amount spent / goal amount) × 100
No webhook sent for exactly 0% progress

Payload

These fields are sent in the payload object of the webhook envelope.

Name	Type	Description
spendingGoalUid	string	Unique identifier of the spending goal
categoryId	string	The category the goal applies to, in the same format as the `categoryId` on transactions, for example `std:a2d41243-ab21-4d02-ac0d-daa3621e4b49`. Custom categories start with `cus:`
percentageOfProgress	number	Current spending as percentage of goal amount

Use the categories endpoint to look up the name of a category from its categoryId.

Example (JSON format)

{
  "id": "abe168ce-1b2f-4c38-9c92-db5730485cb3",
  "eventType": "spendingGoalProgress",
  "userId": "5c79210bbac25ecb5e71ac40",
  "payload": {
    "spendingGoalUid": "goal_12345",
    "categoryId": "std:a2d41243-ab21-4d02-ac0d-daa3621e4b49",
    "percentageOfProgress": 75.5
  }
}

spendingGoalReached and spendingGoalExceeded have the same shape, with eventType set accordingly and percentageOfProgress at 100 or above.

This example uses the JSON format. JWT webhooks carry the same payload fields in a different envelope, and batched webhooks list events without payloads. See Webhook Format.