Skip to main content
Skip table of contents

Push Notifications (Web Hooks)

Overview

The Notifications module allows your client application to get informed about changes in the users' data so that your application can inform your users about those changes. 

Notifications are available only when your client is set up for batch updates of your user's accounts.

More information about the Batch Updates: Automated Update of the Bank Data (Batch Updates)

How it works:

  1. A user sets up one or multiple notification rules which specify what kind of events they want to be informed about (please see how to create a notifications rule in the section below).
    Note that this means that even though it is the client application that will receive finAPI's notifications (finAPI won't send notifications directly to the users), the notification rules are managed by finAPI on a user level, not on a client level. This makes sense as not every user wants to be notified about the same things (or at all).

  2. Whenever a user's accounts/bank connections have been updated during the batch update, finAPI would analyze the result of the update and check if any notification rules have to be applied for the user.

  3. For any rule that "matches" with the result of the update, a notification message will be sent by finAPI to the client application (more precisely: to a specific callback URL userNotificationCallbackUrl that the client application has set up for the respective notification rule when creating it - see the settings in the Client Configuration Resource).

  4. The client application receives the notifications from finAPI, processes them, and forwards the desired information to the respective user. The exact contents of the notification messages that finAPI sends to the client application depend on the type of notification, more details about this can be found in the API documentation - see the section Notification Rules.

Users can edit their notification rules at any time by deleting existing rules or creating new ones. Also, finAPI provides a service to get and search notification rules, which allows you to implement a user-friendly interface for the notifications configuration in your client application.

How to Create Notification Rules

Trigger Create a new notification rule endpoint:

CODE 
POST /notificationRules

Each notification triggered by a notification rule identifies itself via a callbackHandle. The callback handle is an ID of a notification rule that is provided by the client/user that creates the notification rule. It can be used for identifying an instance of a rule, e.g. with "Balance < 0".

There are different kinds of notification rules depending on the triggerEvent.
The trigger event specifies what data you have to pass when creating a rule (specifically, the contents of the parameters attribute), on which events finAPI will send notifications to your client application, as well as what data is contained in those notifications.

Trigger Events


triggerEvent = NEW_ACCOUNT_BALANCE

Rules with this trigger event cause finAPI to send notifications whenever the balance has changed for one or several of the user's bank accounts during the batch update.

The params attribute is optional for this rule type and may accountIds. If not specified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's accounts has a new balance as a result of the batch update.

accountIds can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this attribute is that finAPI will send a (single) notification message only when one or several of the specified accounts got a new balance as a result of the automatic update. If the balance changed for only other accounts which you did not specify in the parameter, then no notification will be sent.

Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in accountIds.

If you do specify the params, it must represent the following JSON object:

CODE 
{
   "accountIds": String
}

Example of the notification message:

CODE 
{
    "notificationRuleId": Number,
    "triggerEvent": "NEW_ACCOUNT_BALANCE",
    "callbackHandle": String,
    "balanceChanges": [{
        "accountId":Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String, 
        "bankConnectionName": String, // encrypted
        "details":String
    }, ...]
 }

balanceChanges: contains an item for each account where the balance changed

details are only set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key*, and which will - once decrypted - represent the following JSON object:

CODE 
{
    "accountNumber": String,
    "iban": String,
    "accountName": String,
    "bankConnectionName": String,
    "oldBalance": Number,
    "newBalance": Number,
    "balanceChange": Number
}

*For More details about how to decrypt data with a Data Decryption Key: please check this article here.

triggerEvent = NEW_TRANSACTIONS

Rules with this trigger event cause finAPI to send notifications whenever new transactions have been downloaded for one or several of the user's bank accounts during an automatic update.

The params attribute is optional for this rule type. If not specified, it means that finAPI will send a (single) notification message to your client application when at least one of the user's accounts has new transactions as a result of the automatic update. The message will contain data about each account that has new transactions (details on what the message looks like below).

If you do specify the params, then it must represent the following JSON object:

CODE 
{
    "accountIds": String,
    "maxTransactionsCount": Number,
    "waitForCategorization": Boolean // available only in API v2+
}

accountIds can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this attribute is that finAPI will send a (single) notification message only when one or several of the specified accounts got new transactions as a result of the automatic update. If new transactions were downloaded only for other accounts which you did not specify in the parameter, then no notification will be sent.

Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the accountIds attribute.

The maxTransactionsCount attribute specifies how many of the new transactions should be included at most in the notification message (this is only relevant if you create the rule with includeDetails=true). The attribute can have a value between 0 and 100 and defaults to 100 if not specified.

The waitForCategorization attribute is optional and defaults to false. You can specify it only when you are on API v2 or greater. Trying to specify the field using API v1 will result in an error. If this attribute is set to true, it means that finAPI will delay the notification up until all transactions have been categorized. If you also use includeDetails=true, the categoryIds and categoryNames will be included in the notification. Note that the fields may still be null, if a transaction wasn’t assigned any category. Also be aware that you need to have automatic categorization enabled for these fields to be populated (see GET /clientConfiguration, field isAutoCategorizationEnabled).

Example of the notification message:

CODE 
{
    "notificationRuleId": Number,
    "triggerEvent": "NEW_TRANSACTIONS",
    "callbackHandle": String,
    "newTransactions": [{
        "accountId": Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted 
        "bankName": String,
        "bankConnectionName": String, // encrypted
        "newTransactionsCount": Number,
        "details": String
    }, ... ]
}

newTransactions: contains an item for each account that got new transactions

accountName: contains an encrypted string that you will have to decrypt using your client's data decryption key.

accountNumber: contains an encrypted string that you will have to decrypt using your client's data decryption key.

bankConnectionName: contains an encrypted string that you will have to decrypt using your client's data decryption key.

accountIban: contains an encrypted string that you will have to decrypt using your client's data decryption key. The attribute may be null.

details only set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

CODE 
{
    "transactionDetails": [{
        "id": Number,
        "finapiBookingDate": String, // german time, in format yyyy-MM-dd HH:mm:ss.SSS
        "bankBookingDate": String, // german time, in format yyyy-MM-dd HH:mm:ss.SSS
        "amount": Number,
        "counterpartName": String,
        "counterpartIban": String,
        "purpose": String,
        "isAdjustingEntry": Boolean, // since finAPI v1.30.0
        "categoryId": Number,
        "categoryName": String
}, ... ] }

The transactionDetails attribute contains a list of the new transactions (at most maxTransactionsCount), each with its details. The transactions are ordered by bankBookingDate, descending.
Note that you should assess the fields categoryId and categoryName only when the rule was created with waitForCategorization=true.


triggerEvent = BANK_LOGIN_ERROR

Rules with this trigger event cause finAPI to send notifications whenever the automatic update could not update one or several of the user's bank connections because the login at the bank server failed.

The params attribute is optional for this rule type. If not specified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's bank connections could not get updated in the automatic update. The message will contain data about each bank connection that could not get updated (details on what the message looks like below).

If you do specify the params, it must represent the following JSON object:

CODE 
{
    "bankConnectionIds": String
}

bankConnectionIds can contain a string of one or more (comma-separated) identifiers of the user's bank connections. The effect of specifying this attribute is that finAPI will send a (single) notification message only when one or several of the specified connections could not get updated in the automatic update. If the update failed only for other connections which you did not specify in the parameter, then no notification will be sent.

Note that when you want to receive separate notifications for the individual bank connections, you would have to create several rules, each having another bank connection identifier specified in the bankConnectionIds attribute.

Example of the notification message:

CODE 
{
    "notificationRuleId": Number,
    "triggerEvent": "BANK_LOGIN_ERROR",
    "callbackHandle": String,
    "loginErrors": [{
        "bankConnectionId": Number,
        "bankName": String,
        "bankConnectionName": String, // encrypted
        "errorCode": String,
        "details": String
    }, ... ]
}

loginErrors contains an item for each bank connection where the login failed

errorCode will either be WRONG_CREDENTIALS, which means that the login failed because the stored credentials of the bank connection are incorrect, or it will not be set at all, which means that login failed for an unknown reason (e.g. timeout to the bank server or other technical problems)

details only set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

CODE 
{
    "errorMessage": String
}

The errorMessage attribute contains the error message that the bank server sent when denying the login.

triggerEvent = FOREIGN_MONEY_TRANSFER

Rules with this trigger event cause finAPI to send notifications whenever new outgoing foreign transactions have been imported during an automatic update. An outgoing foreign transaction is a transaction where:

  • the amount is negative

  • the counterpart IBAN depicts a bank from a different country than the source account's bank

The params attribute is optional for this kind of rule. If not specified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's accounts has a new outgoing foreign transaction after an automatic update. The message will contain data for each account where new outgoing foreign transactions were downloaded (details on what the message looks like below).

If you do specify the params, then it must represent the following JSON object:

CODE 
{
    "accountIds": String
}

accountIds can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this attribute is that finAPI will send a (single) notification message only when one or several of the specified accounts got new outgoing foreign transactions as a result of the automatic update. If new such transactions were received for only other accounts which you did not specify in the parameter, then no notification will be sent.

Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the accountIds attribute.

Example of the notification message:

CODE 
{
    "notificationRuleId": Number,
    "triggerEvent": "FOREIGN_MONEY_TRANSFER",
    "callbackHandle": String,
    "newTransactions": [{
        "accountId": Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String,
        "bankConnectionName": String, // encrypted
        "transactionsCount": Number,
        "details": String
    }, ... ]
}

newTransaction contains an item for each account where at least one new outgoing foreign transaction has been imported

accountName: contains an encrypted string that you will have to decrypt using your client's data decryption key.

accountNumber: contains an encrypted string that you will have to decrypt using your client's data decryption key.

accountIban: contains an encrypted string that you will have to decrypt using your client's data decryption key. May be null.

bankConnectionName: contains an encrypted string that you will have to decrypt using your client's data decryption key. May be null.

transactionsCount contains the number of new outgoing foreign transactions for the respective account

details and is only set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

CODE 
{
   "transactionDetails": [
      {
         "id": Number,
         "finapiBookingDate": String, // german time, in format yyyy-MM-dd HH:mm:ss.SSS
         "bankBookingDate": String, // german time, in format yyyy-MM-dd HH:mm:ss.SSS
         "amount": BigDecimal,
         "counterpartName": String,
         "counterpartAccountNumber": String,
         "counterpartIban": String,
         "counterpartBlz": String,
         "counterpartBic": String,
         "purpose": String
      },...
   ] 
}


triggerEvent = LOW_ACCOUNT_BALANCE

Rules with this trigger event cause finAPI to send notifications whenever an account's balance drops below the given balanceThreshold during an automatic update.

The params attribute is required for this rule type. It may contain three nested attributes:

  • accountIds (optional)

  • balanceThreshold (required).

If the accountIds is not specified, then finAPI will send a (single) notification message to your client application when at least one of the user's accounts got a new balance, which is lower than the given balanceThreshold.

accountIds can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this attribute is that finAPI will send a (single) notification message only when one or several of the specified accounts got a balance below the given balanceThreshold as a result of the batch update. If such a balance has been received for only other accounts which you did not specify in the parameter, then no notification will be sent.

Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the accountIds attribute.

balanceThreshold is required. If the account's balance drops below the value of this parameter, a notification will be sent. The message will contain data about each account where the balance drops below the balanceThreshold (details on what the message looks like below).

params must represent the following JSON object:

CODE 
{
    "accountIds": String,
    "balanceThreshold": BigDecimal
}

Example of the notification message:

CODE 
{
    "notificationRuleId": Number,
    "triggerEvent": "LOW_ACCOUNT_BALANCE",
    "callbackHandle": String,
    "balanceThreshold": BigDecimal,
    "balanceChanges": [{
        "accountId":Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String,  
        "bankConnectionName": String, // encrypted
        "details":String
    }, ...]
}

balanceThreshold contains the value, that was set during notification rule creation

balanceChanges contains an item for each account where the balance changed

accountName: contains an encrypted string that you will have to decrypt using your client's data decryption key.

accountNumber: contains an encrypted string that you will have to decrypt using your client's data decryption key.

accountIban: contains an encrypted string that you will have to decrypt using your client's data decryption key. May be null.

bankConnectionName: contains an encrypted string that you will have to decrypt using your client's data decryption key. May be null.

details only set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

CODE 
{
    "accountNumber": String,
    "iban": String,
    "accountName": String,
    "bankConnectionName": String,
    "oldBalance": Number,
    "newBalance": Number,
    "balanceChange": Number
}


triggerEvent = HIGH_TRANSACTION_AMOUNT

Rules with this trigger event cause finAPI to send notifications whenever a new transaction with an absolute amount higher than or equals to the given absoluteAmountThreshold has been imported during the batch update.

The params attribute is required for this rule type. It may contain three nested fields:

  • accountIds(optional)

  • absoluteAmountThreshold (required)

  • maxTransactionsCount (optional).

If accountIds is not specified, then finAPI will send a (single) notification message to your client application when at least one of the user's accounts have new transactions with an absolute amount higher than or equal to the given absoluteAmountThreshold.

accountIds can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this attribute is that finAPI will send a (single) notification message only when one or several of the specified accounts got new transactions with the specified criteria as a result of the batch update.

If you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in the accountIds.

If the absolute transaction's amount is higher than or equal to the absoluteAmountThreshold then this transaction will be included in the notification details (if details are enabled for the rule).

The maxTransactionsCount attribute specifies how many of the transactions should be included at most in the notification message (this is only relevant if you create the rule with includeDetails=true). The attribute can have a value between 0 and 100 and defaults to 100 if not specified.

The message will contain data about each account that got a transaction with an absolute amount higher than or equal to the given absoluteAmountThreshold (details on what the message looks like below).

params must represent the following JSON object:

CODE 
{
    "accountIds": String,
    "absoluteAmountThreshold": BigDecimal,
    "maxTransactionsCount": Number
}

Example of the notification message:

CODE 
{
    "notificationRuleId": Number,
    "triggerEvent": "HIGH_TRANSACTION_AMOUNT",
    "callbackHandle": String,
    "absoluteAmountThreshold": BigDecimal,
    "newTransactions": [{
        "accountId":Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String,  
        "bankConnectionName": String, // encrypted
        "newTransactionsCount": Number,
        "details": String
    }, ...]
}

absoluteAmountThreshold contains the value, that was set during the notification rule creation.

newTransactionscontains an item for each account where new transactions have been imported which apply to the given criteria.

accountName: contains an encrypted string that you will have to decrypt using your client's data decryption key.

accountNumber: contains an encrypted string that you will have to decrypt using your client's data decryption key.

accountIban: contains an encrypted string that you will have to decrypt using your client's data decryption key. May be null.

bankConnectionName: Contains an encrypted string that you will have to decrypt using your client's data decryption key. May be null.

details only set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

CODE 
{
    "transactionDetails": [{
        "id": Number,
        "finapiBookingDate": String, // german time, in format yyyy-MM-dd HH:mm:ss.SSS
        "bankBookingDate": String, // german time, in format yyyy-MM-dd HH:mm:ss.SSS
        "amount": Number,
        "counterpartName": String,
        "counterpartIban": String,
        "purpose": String,
        "isAdjustingEntry": Boolean // since finAPI v1.30.0
}, ... ] }


triggerEvent = CATEGORY_CASH_FLOW

Rules with this trigger event cause finAPI to send notifications whenever new transactions have been downloaded during the batch update that have been categorized with a certain category.

params consists of three attributes:

  • accountIds (optional)

  • categoryId (required)

  • includeChildCategories (optional).

If accountIds is not specified, then it means that finAPI will send a (single) notification message to your client application when at least one of the user's accounts has new transactions that have been categorized with the specified category. The message will contain data about each account that has new categorized transactions (details on what the message looks like below).

If specified, the accountIds can contain a string of one or more (comma-separated) identifiers of the user's accounts. The effect of specifying this attribute is that finAPI will send a (single) notification message only when one or several of the specified accounts got new transactions that have been categorized with the specified category as a result of the automatic update. If new transactions were categorized only for other accounts which you did not specify in the parameter, then no notification will be sent. Note that when you want to receive separate notifications for the individual accounts, you would have to create several rules, each having another account identifier specified in accountIds.

categoryId specifies which category you want the notifications to be based on.

With the attribute includeChildCategories, you can specify whether you want to get notified only about transactions with the exact category that you have specified (includeChildCategories=false), or whether you also want to get notified about transactions whose category is a sub-category of the specified category (includeChildCategories=true).

If not specified, the default value of the includeChildCategories flag is 'true'.

Note that if the specified categoryId already represents a sub-category, then the includeChildCategories has no effect (as sub-categories cannot have further sub-categories).

params must represent the following JSON object:

CODE 
{
   "accountIds": String, // optional
   "categoryId": String,
   "includeChildCategories": Boolean // optional
}


Example of the notification message:

CODE 
{
   "notificationRuleId":Number,
   "triggerEvent":"CATEGORY_CASH_FLOW",
   "callbackHandle":String,
   "categoryId":Number,
   "categoryName":String,
   "includeChildCategories":Boolean,
   "categoryCashFlows":[
      {
        "accountId":Number,
        "accountName": String, // encrypted
        "accountNumber": String, // encrypted
        "accountIban": String, // encrypted
        "bankName": String, 
        "bankConnectionName": String, // encrypted
        "details":String
      }
      ,...
   ]
}

 

  • categoryId is the specified category identifier.

  • includeChildCategories depicts whether this notification may contain transactions of sub-categories of the specified category.

  • categoryName will only be set if the rule was created with includeDetails=true, and will in this case contain the name of the specified category as an encrypted string that you must decrypt using your client's data decryption key.

  • categoryCashFlows contains an item for each account that got new transactions that have been categorized with the specified category.

  • accountName: contains an encrypted string that you will have to decrypt using your client's data decryption key.

  • accountNumber: contains an encrypted string that you will have to decrypt using your client's data decryption key.

  • accountIban: contains an encrypted string that you will have to decrypt using your client's data decryption key. May be null.

  • bankConnectionName: Contains an encrypted string that you will have to decrypt using your client's data decryption key. May be null.

  • details only set if the rule was created with includeDetails=true. In this case, it will contain an encrypted string that you will have to decrypt using your client's data decryption key, and which will - once decrypted - represent the following JSON object:

CODE 
{
   "transactions":[
      {
         "id":Number,
         "categoryId": Number,
         "categoryName": String,
         "finapiBookingDate": String, // german time, in format yyyy-MM-dd HH:mm:ss.SSS
         "bankBookingDate": String, // german time, in format yyyy-MM-dd HH:mm:ss.SSS
         "amount":Number,
         "counterpartName": String,
         "counterpartIban": String,
         "purpose": String
      }
      ,...
   ]
}

transactions contain a list of the new transactions that have been categorized with the specified category (or one of its sub-categories, if the includeChildCategories flag is true), each with its details. The transactions are ordered by bankBookingDate, descending.


triggerEvent = NEW_TERMS_AND_CONDITIONS

Rules with this trigger event cause finAPI to send notifications whenever finAPI's batch update detects that it cannot update the bank connections of a user because there are new terms and conditions that the user has not yet accepted.

This rule type does not specify any additional parameters or details.

Example of the notification message:

CODE 
{
    "notificationRuleId": Number,
    "triggerEvent": "NEW_TERMS_AND_CONDITIONS",
    "callbackHandle": String
}

 


Unique constraints / error messages


The accountIds / bankConnectionIds attributes are unique meaning you can´t create one trigger event more than once for the same parameters (exception: trigger event CATEGORY_CASH_FLOW, see below).

If you try to create a second notification rule with the same parameters an error message is shown "Notification rule with given parameters already exists."

The accountIds attribute is unique for the following trigger events:

  • NEW_ACCOUNT_BALANCE

  • NEW_TRANSACTIONS

  • FOREIGN_MONEY_TRANSFER

  • LOW_ACCOUNT_BALANCE

  • HIGH_TRANSACTION_AMOUNT

  • for trigger event CATEGORY_CASH_FLOW the accountIds attribute is unique in combination with one categoryId (surely you can create several CATEGORY_CASH_FLOW notification rules for one account with several categoryIds)

The bankConnectionIds attribute is unique for the following trigger event:

  • BANK_LOGIN_ERROR

Please note that it is still possible to have more than one rule for one account.
Here is an example:

  • Creation of a trigger event "NEW_ACCOUNT_BALANCE" without any parameters.

  • Creation of a 2nd trigger event "NEW_ACCOUNT_BALANCE" with one specified accountId(123)

  • Creation of a 3rd trigger event "NEW_ACCOUNT_BALANCE" with two specified accountIds(123, 124)

  • All trigger events are created

Whenever the balance changes for accountId 123 three notifications are sent!
There is no priority setting or overwriting of rules.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close