These docs are for v2.11. Click to read the latest docs for v2.13.

Notifications

Whenever an account gets synchronized with the associated financial provider and new data is fetched, your application can asynchronously be notified via webhooks about certain events. For which events your application gets called depends on the notification key used, whose format is described in the following section.

For a notification to be considered as delivered successfully, the webhook endpoint should return HTTP response codes in the range of 2xx or 3xx. Everything else will be assumed an error.

Callback Request Headers

When a notification is triggered, the configured callback endpoint is called by the finX API setting the User-Agent header to finx-notification/<finx-api-version>. E.g.

User-Agent: finx-notification/1.0.0

Observe Keys

When configuring a new notification, you have to specify an observe key which defines the trigger condition for the notification. The observe key is composed of a path and a number of query parameters, similar to a URL without scheme and host part.

A client is only allowed to configure a notification of a certain type if he has the required scope for this specific notification.

Account balance

Triggered when the respective account balance changes

ItemValue
Key/rest/accounts/{account-id}/balance?inferior_limit=<int>
Scopebalance=ro

Parameters

NameInDescription
account-idpathfinX account ID
inferior_limitqueryTrigger if the balance of the account is below this value

Transactions of Account

Triggered when an account has received new transactions

ItemValue
Key/rest/accounts/{account-id}/transactions?<params>
Scopetransactions=ro

Parameters

All query-parameters for this observe key can be combined with include_pending but not amongst each other.

NameInDescription
account-idpathfinX account ID.
include_pendingqueryAlso consider pending transactions.
more_expenses_then_depositsqueryTrigger if the sum of expenses in the current month exceeds the sum of deposits.
current_month_expense_goalqueryTrigger if the sum of expenses in the current month exceeds the provided value.
single_expense_goalqueryTrigger for expense transactions exceeding the provided value.
single_deposit_goalqueryTrigger for expense transactions exceeding the provided value.
purposequeryTrigger on transactions whose purpose contains the provided value.
namequeryTrigger on transactions whose sender/receiver name contains the provided value.

All transactions

ItemValue
Key/rest/transactions
Scopetransactions=ro

Parameters

All query-parameters for this observe key can be combined with include_pending but not amongst each other.

NameInDescription
include_pendingqueryAlso consider pending transactions.
more_expenses_then_depositsqueryTrigger if the sum of expenses in the current month exceeds the sum of deposits.
current_month_expense_goalqueryTrigger if the sum of expenses in the current month exceeds the provided value.
single_expense_goalqueryTrigger for expense transactions exceeding the provided value.
single_deposit_goalqueryTrigger for expense transactions exceeding the provided value.
purposequeryTrigger on transactions whose purpose contains the provided value.
namequeryTrigger on transactions whose sender/receiver name contains the provided value.

Auto-sync error

Triggered when the saved PIN of a user is not accepted from the corresponding bank while performing an auto sync.

ItemValue
Key/rest/accounts/{account-id}/sync?wrong_pin=1
Scopebalance=ro transactions=ro

Parameters

NameInDescription
account-idpathfinX account ID
wrong_pinqueryTrigger if the PIN of the provider access was reported to be in this state.

Consent rejected

Triggered when the consent the user granted earlier is rejected by the bank (for example when the consent is expired or the user has already rejected the consent on bank side).

ItemValue
Key/rest/accesses?consent_rejected=1
Scopebalance=ro transactions=ro

Test-notification

Triggered immediately. This special notification key can be used to test the delivery of
notifications. The notification message will be sent immediately and no registration occurs.

ItemValue
Key/rest/notifications/test
Scope

Notification payload

The notification payload you receive on the webhook endpoint is a JSON object with the following fields:

KeyDescription
notification_idThe ID of the notification in finx, you also get the ID of the notification when creating it
notification_uriThe URI you provided when creating the notification, this is the URI of the endpoint which will receive the webhook call on your end
observe_keyThe observe_key used to create the notification
stateThis is the value you provided when creating the notification, it could be used to identify the webhook on your end
hrefWhere supported, this is the path you can HTTP GET from finx that will return you the objects that triggered the notification (currently only "Consent rejected" notifications support this, you get an href to a credential object which was rejected by the Bank)