Institution Changes

Lambda: prod-insight-institution-change-handler
Trigger: SQS (prod-insight-institution-change-handler-sqs-tap, via account_change_detected_rule EventBridge rule)

The institution-change-handler clears stale employment and income-verification records when a user connects a new bank institution. This prevents payday prediction and income detection from using data associated with a bank account the user no longer has linked.

Trigger and Event Source

The Lambda is triggered by the account_change_detected_rule EventBridge rule, which matches events from the Transactions Service API Lambda:

EventBridge Field Value

Source

txn-service.api

Detail-Type

new_bank_account_added

These events are routed to the prod-insight-institution-change-handler-sqs-tap SQS queue. Each message detail contains a user_id and account_id identifying the newly added account.

This event source (txn-service.api) is distinct from the new_account event (txn-service.feeder) that triggers the balance-alert Lambda. The new_bank_account_added event fires when a user explicitly connects a new bank institution through the app; new_account fires when the Transactions Service feeder processes a new account from an existing Plaid connection.

Processing Flow

institution_change_handler_event_tap SQS message
  └─▶ Handler.Handle(user_id, account_id)
        ├─▶ DynamoDB IncomeVerificationRepo.Delete(user_id)
        │     └─ deletes income_verification entity from prod-pave table
        └─▶ RDS employment.Delete(user_id)
              └─ deletes employment record from PostgreSQL employment table

Both deletes are performed in sequence. If either fails, the error is returned and the SQS message is added to the batch failure list for retry (up to the queue’s maximum receive count, then routed to the DLQ).

What Gets Cleared

Store Record Cleared

prod-pave DynamoDB (income_verification entity)

Manual income verification data entered by the user (employer, salary, pay frequency, start date) and any augmentation from MX or Ollie verification providers.

RDS employment table

The user’s employment record used for payday prediction, including employer details and income frequency.

Nothing else is cleared. Pave insight data (recurring, ritual, income, scores) is not touched — it will be naturally refreshed the next time the feeder processes a transaction event for the user’s new bank connection.

Error Handling

The handler validates that both user_id and account_id are non-empty before proceeding. A nil event or missing fields returns ErrEventNil and fails the SQS batch item immediately without retrying.

Delete operations that return errors from DynamoDB or RDS fail the batch item and trigger a retry. Retries are safe — both delete operations are idempotent.

Related Pages