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

Refresh Intent Events

Emitted when an on-demand refresh completes. Use this instead of polling GET /v1/refresh-intents/{id}.

Event Type	Description
refresh_intent.completed	All connections in the refresh intent have finished syncing (completed or failed)

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"
  }
}
            

Refresh Intent Event Payload

Unlike other events, refresh_intent.completed is scoped to an intent rather than a single connection, so there is no top-level connectionId field. Per-connection status is nested in the connections array.

json

              {
  "id": "evt_01HXYZ...",
  "type": "refresh_intent.completed",
  "created_at": "2026-01-20T14:30:00.000Z",
  "data": {
    "eventId": "evt_01HXYZ...",
    "type": "refresh_intent.completed",
    "occurredAt": "2026-01-20T14:30:00.000Z",
    "clientId": "cli_01H8X9KQWERTY12345",
    "refreshIntentId": "01H8X9ABCDEF67890",
    "connections": [
      {
        "connectionId": "conn_01H8X9ABCDEF67890",
        "status": "completed",
        "error": null
      },
      {
        "connectionId": "conn_01H8X9ABCDEF67891",
        "status": "failed",
        "error": "transient_failure"
      }
    ]
  }
}
            

💡 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.

When you receive refresh_intent.completed, check each connection's status in the connections array and fetch updated data for those with "status": "completed".