Webhook Event Types

Araucaria emits three categories of events: connection events, account events, and transaction events.

Connection Events

Emitted when a connection's status changes. Each event corresponds to a state in the connection lifecycle.

Event Type	Description
connection.created	Connection created, waiting for credentials
connection.credentials_submitted	User submitted credentials via widget
connection.verifying	Worker is verifying credentials with the bank
connection.connected	Successfully connected, accounts available
connection.mfa_required	Bank requires multi-factor authentication
connection.failed_auth	Invalid credentials provided
connection.error	Unexpected error during connection
connection.disconnected	Connection was disconnected

Account Events

Emitted when account data changes. Fetch the latest data when receiving these events.

Event Type	Description
accounts.updated	Account data has been updated, fetch latest transactions

Transaction Events

Emitted when transaction data changes. Use these to keep your local transaction records in sync.

Event Type	Description
transaction.deleted	A transaction was removed during deduplication or correction

Connection Event Payload

json

              {
  "id": "evt_01HXYZ...",
  "type": "connection.connected",
  "created_at": "2026-01-20T14:30:00.000Z",
  "data": {
    "eventId": "evt_01HXYZ...",
    "type": "connection.connected",
    "occurredAt": "2026-01-20T14:30:00.000Z",
    "clientId": "cli_01H8X9KQWERTY12345",
    "connectionId": "conn_01H8X9ABCDEF67890",
    "previousStatus": "verifying",
    "error": null
  }
}
            

Account Event Payload

json

              {
  "id": "evt_01HXYZ...",
  "type": "accounts.updated",
  "created_at": "2026-01-20T14:30:00.000Z",
  "data": {
    "eventId": "evt_01HXYZ...",
    "type": "accounts.updated",
    "occurredAt": "2026-01-20T14:30:00.000Z",
    "clientId": "cli_01H8X9KQWERTY12345",
    "connectionId": "conn_01H8X9ABCDEF67890",
    "accountId": "acc_01H8X9KQWERTY12345"
  }
}
            

Transaction Event Payload

json

              {
  "id": "evt_01HXYZ...",
  "type": "transaction.deleted",
  "created_at": "2026-01-20T14:30:00.000Z",
  "data": {
    "eventId": "evt_01HXYZ...",
    "type": "transaction.deleted",
    "occurredAt": "2026-01-20T14:30:00.000Z",
    "clientId": "cli_01H8X9KQWERTY12345",
    "connectionId": "conn_01H8X9ABCDEF67890",
    "accountId": "acc_01H8X9KQWERTY12345",
    "transactionId": "txn_01H8X9KQWERTY12345"
  }
}
            

💡 Next Steps

When you receive connection.connected, call GET /v1/connections/{connectionId}/accounts to retrieve accounts.

When you receive accounts.updated, call GET /v1/accounts/{accountId} for the updated balance and GET /v1/accounts/{accountId}/transactions for new transactions.

When you receive transaction.deleted, remove the transaction from your local records if you store them.